All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
1.1.0 - 2026-11-06
websites()/websites_async()returned only the first page of Umami's paged/api/websiteslisting, silently truncating the list for accounts with more websites than one page. They now follow thepageparameter until the reportedcountis reached (or a page adds nothing new, so a server that ignorespagecannot loop) and return the complete list. Single-page accounts still make one request.- Self-hosted sends (
new_event(),new_page_view(),new_revenue_event()and async twins) sent the literal headerAuthorization: Bearer Nonewhen nobody had calledlogin(). The header is now omitted unless a token is present; Umami's/api/sendignores it either way, so recorded data is unchanged. login()/login_async()now reject whitespace-only usernames and passwords withValidationError, matchingset_url_base()andset_cloud_api_key(); before, they went to the server and came back as a 401. The empty-username message also now saysUsername cannot be emptyinstead ofEmail.
- New user guide on the docs site: Getting started, Sending events, Authentication, Querying stats, Troubleshooting, Testing and CI, Configuration, How it works, and FAQ. The guide pages are also appended to
llms-full.txt. - The agent skill (
skill.md,.well-known/agent-skills/umami-analytics/SKILL.md,.well-known/skills/default/SKILL.md) is now hand-written fromumami/skills/umami-analytics/SKILL.mdand teaches the rules of the package (setup order, self-hosted vs Cloud, whatdisable()silences,distinct_id, the bot filter, what each error means) instead of listing API names. The skill is renamed fromumamitoumami-analytics, so its.well-knownpath changed.umami/skill_extra_body.mdis folded into it and removed. - Every public function, model, and exception now has an
Example:section in its docstring, rendered on the reference pages and inllms-full.txt. The package docstring states that there is no CLI and no environment variables are read, and names the three exception types callers see. - Docstring
Raises:sections fornew_event(),new_revenue_event(), and their async twins now list a blankevent_nameas aValidationErrorcause. - README: install shows
uv addandpip installand warns about the unrelatedumamipackage; the Documentation section links each guide page; the tracking-disabled bullets say exactly what still contacts the server and that the send functions return{}; the Cloud section says the two modes are exclusive; the "Login" feature bullet no longer implies username/password login works on Cloud. scripts/build_docs.pynow fails the build whenllms.txt,llms-full.txt,skill.md, the.well-knownskill copies, the user guide,sitemap.xml,robots.txt, orsearch.jsonare missing from the output, or whenllms-full.txtlacks a guide page. The post-build patch of the generated skill's install command is removed; Great Docs fixed that in 0.16.0 and the skill is hand-written now. Thegreat-docsdev dependency is floored at 0.17.0, the version the build was verified on, in both the[dev]extra and a newumami/requirements-dev.txtthat mirrors it.
First stable release. The package is now marked Development Status :: 5 - Production/Stable (it has
been used in production at Talk Python Training for some time) and follows SemVer
from here forward.
- Promoted the trove classifier from
4 - Betato5 - Production/Stable, and added theTyping :: Typedclassifier to advertise the bundledpy.typedmarker. - Expanded the PyPI keyword set (added web-analytics, privacy, tracking, metrics, events, page-views, telemetry, statistics, self-hosted, async, httpx, pydantic, sdk, api-client) for better discoverability.
pydantic.Field(description=...)metadata on every response-model field, plus agriffe-pydanticdev dependency, enriching the response models for IDEs, JSON schema, and future API-reference rendering. Note: the current Great Docs version (0.13.0) does not load griffe extensions, so the rendered field docs still come from the docstringAttributes:sections; the Field descriptions will surface on the docs site once the generator loads the extension.
- Synchronous send functions now return the Umami API's JSON response as a dict (and
{}when tracking is disabled), matching their async twins. Previouslynew_event(),new_revenue_event(), andnew_page_view()returnedNone;new_page_view_async()also now returns the response dict instead ofNone. - Missing or blank required event fields (hostname, website_id, event_name) now raise
umami.errors.ValidationErrorinstead of a bareException, so they can be caught alongside the SDK's other validation errors. Website.shareId,Website.resetAt, andWebsite.deletedAtare now optional (defaultNone), so a websites response that omits those keys no longer raisespydantic.ValidationError.- README now points to the new documentation site at https://mkennedy.codes/docs/umami-python/ (added status badges, a documentation pointer near the top, and a "Documentation" section linking the full API reference). Docs-only change — no code or packaging changes.
- Docstrings across the public API were expanded and corrected for the generated documentation
site (Great Docs renders them verbatim, and they feed
llms.txt). AddedRaises:sections to every raising function; fixedwebsite_stats()/website_stats_async()to document their real return type (models.WebsiteStats, not the nonexistentWebsiteStatsResponse); removed unprofessional/inaccurate prose fromverify_token(the "minutes, hours, or years" hedge) andnew_event(the "not sure how this is different" aside); correctednew_page_viewwording (visitor; theuauser-agent string); clarified thatdisable()still validates before skipping the HTTP request and that both affect only the send functions; documented all response models and exception classes; added a package module docstring; and added runnable usage examples. Docstring-only — no code or behavior changes.
validate_event_datano longer lets a whitespace-onlyevent_namethrough (the check usedand, so whitespace bypassed it; it now usesor).
0.6.25 - 2026-06-07
distinct_idsupport innew_event,new_page_view, andnew_revenue_eventpayloads (sync and async), sent to Umami as payload fieldid- Umami Cloud API-key authentication via
set_cloud_api_key(key, region=None)andclear_cloud_api_key(). In Cloud mode, data/management calls route tohttps://api.umami.is/v1[/region]with anx-umami-api-keyheader, and events are sent tohttps://cloud.umami.is/api/send— noset_url_base()orlogin()required. Existing self-hosted (login()+ token) usage is byte-for-byte unchanged. Addedurls.mefor Cloud key validation inverify_token/verify_token_async. In Cloud mode,heartbeat()/heartbeat_async()check liveness via the authenticated/meendpoint (Cloud has no/api/heartbeat), andlogin()/login_async()raiseOperationNotAllowedErrorto fail fast (the API key is the credential — there is no username/password login on Cloud).
validate_stateerror messages now mentionset_cloud_api_key()alongsideset_url_base()/login(). Same exception type (OperationNotAllowedError) and trigger conditions; text only.- Response models are more tolerant of variant/partial responses:
WebsiteStats.comparisonandWebsite.userare now optional, andWebsiteacceptscreateUser(returned by team-website listings, whereuserIdis 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_basevalidation, thevalidate_stateguards, thelogin/login_asynchappy path and response-model deserialization (LoginResponse,WebsitesResponse),websites/websites_async, thedisable()no-op (asserting no HTTP request is made),ip_addresspayload inclusion/omission, explicit-arg-overrides-defaults precedence,heartbeat_asyncself-hosted, and theverify_token/heartbeatfailure branches. Added a sync/async parity harness and consolidated the per-file HTTP mock builders into a sharedtests/_mocks.py(net ~210 fewer lines). No production behavior changed.
website_stats_async()sent its date range as snake_casestart_at/end_atquery params, which the Umami API ignores — it silently returned all-time stats regardless of the requested window. Now sends camelCasestartAt/endAt, matching the syncwebsite_stats(). (#18)active_users()andactive_users_async()read the active-visitor count from a non-existentxkey, so they always returned0. They now read Umami's currentvisitorskey (falling back to the legacyxkey for compatibility). (#19)website_stats()/website_stats_async()sent theirurlandhostfilters 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 publicurl/hostkeyword arguments are unchanged; they now map to the currentpath/hostnamewire names. (#20)heartbeat()/heartbeat_async()issued aPOSTto/api/heartbeat, which current Umami answers with405 Method Not Allowed; the broad exception handler swallowed the error so the call always returnedFalseeven against a healthy server. They now issue aGET(the endpoint returns{"ok": true}).new_event()andnew_revenue_event()(sync) defaultedurlto'/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.
0.5.24 - 2026-06-04
- Migrated HTTP backend from
httpxtohttpx2, imported asimport httpx2 as httpxso all call sites remain unchanged - Files:
umami/umami/impl/__init__.py,umami/requirements.txt,umami/pyproject.toml,pyrefly.toml,README.md,umami/README.md
- Motivated by supply-chain/maintainer-governance concerns around
httpx(stalled releases, locked-down issues/discussions). Confirmhttpx2is the intended, API-compatible fork before publishing this release.
0.4.23 - 2026-03-12
new_revenue_event()andnew_revenue_event_async()for tracking revenue with Umami's new revenue feature- Revenue events automatically inject
revenue(float) andcurrency(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'andcurrency='USD'for simple usage - 15 new tests covering sync/async revenue events, validation, and edge cases
0.3.22 - 2026-02-02
new_event_asynccrashed withbinascii.Errordue to erroneousbase64.b64decode/json.loadscalls on the plain-JSON API response; now returnsresp.json()directly, matching the other event and page-view methods
- Unused
base64andjsonimports fromumami/impl/__init__.py
- Change-log preservation section for tracking historical release details
- Pyrefly configuration file treating
umami/umamipackage as type-resolution root
- 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
WebsiteStatsto use plain integers instead of customMetrictype - Thanks @rubitcat (#15) - Updated
ruff.tomlto enforce consistent import ordering
- Suppressed and cleaned up unnecessary type-checking warnings
- Development and testing tracking options to disable tracking for dev/test environments
- When tracking is disabled: no HTTP requests are made, API calls still validate parameters, all other functions work normally, functions return appropriate values for compatibility
- Documentation for heartbeat check feature and new methods (
get_heartbeat,enable/disable)
- Sorted imports in various files to improve code organization and readability
- Fixed minor typo in documentation
- Asynchronous (
heartbeat_async) and synchronous (heartbeat) versions of the heartbeat function for improved import flexibility - Website stats and active users functions (
website_stats,active_users) - Thanks @orangethewell
- Login API data handling corrected from
datatojsonparameter
- Optimized heartbeat function execution flow for improved performance
- Python 3.13 and 3.14 support
- API call method fix: corrected the use of
datainstead ofjsonin login API calls
is_logged_in() -> boolmethod to check whether login has been called and was successful
- Heartbeat function (from 0.1.14 release)
- Schema change compatibility from Umami 2.9 to 2.10 on websites response
- Heartbeat API endpoint
- IP address support in
new_eventandnew_page_viewpayloads (and async variants) - Prepares for Umami IP data field feature (see umami-software/umami#2479)
- Ability to pass alternative user agent to events (note: Umami blocks what it perceives as bots)
new_page_view()andnew_page_view_async()methods
- Dropped auth requirement for new event (not needed, see #1)
- Platform type (e.g. Windows) to user agent
- Doc strings to most methods
- Better validation for some functions
- Custom error types for validation