Menu
Umami Analytics Client for Python. Use when writing Python code that uses the umami package.
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/mikeckennedy/umami-python --skill umamiThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
Based on SOC occupation classification
| name | umami |
| description | Umami Analytics Client for Python. Use when writing Python code that uses the umami package. |
| license | MIT |
| compatibility | Requires Python >=3.10. |
Umami Analytics Client for Python
uv pip install umami-analytics
One-time setup. set_url_base() is required before any operation; Cloud users call set_cloud_api_key() instead.
set_url_base: Set the base URL of your self-hosted Umami instanceset_website_id: Set the default website ID used for subsequent callsset_hostname: Set the default hostname used when sending events and page viewsset_cloud_api_key: Authenticate against Umami Cloud with an API key instead of login()clear_cloud_api_key: Exit Cloud mode and return to self-hosted/token behaviorenable: Enable event and page view trackingdisable: Disable event and page view trackingRequired for the query endpoints and verify_token. Not needed to send events.
login: Log into a self-hosted Umami instance and retrieve a temporary auth tokenlogin_async: Log into a self-hosted Umami instance and retrieve a temporary auth tokenis_logged_in: Whether a credential is currently set locallyverify_token: Verify that the currently stored credential is still validverify_token_async: Verify that the currently stored credential is still validSend custom events, revenue, and page views. No login required — only a URL base and a website id/hostname.
new_event: Create a new custom event in Umami for the given website_id and hostnamenew_event_async: Create a new custom event in Umami for the given website_id and hostnamenew_revenue_event: Create a new revenue event in Umami. This is a convenience wrapper aroundnew_revenue_event_async: Create a new revenue event in Umami. This is a convenience wrapper aroundnew_page_view: Create a new page view event in Umami for the given website_id and hostnamenew_page_view_async: Create a new page view event in Umami for the given website_id and hostnameRead analytics back out. Requires login (or a Cloud API key).
websites: All the websites that are registered in your Umami instancewebsites_async: All the websites that are registered in your Umami instancewebsite_stats: Retrieves the statistics for a specific website over a date rangewebsite_stats_async: Retrieves the statistics for a specific website over a date rangeactive_users: Retrieves the number of currently-active visitors for a specific websiteactive_users_async: Retrieves the number of currently-active visitors for a specific websiteCheck Umami server connectivity.
heartbeat: Check whether the configured Umami server is reachable and healthyheartbeat_async: Check whether the configured Umami server is reachable and healthyPydantic models returned by the query functions.
models.WebsitesResponsemodels.Websitemodels.WebsiteStatsmodels.WebsiteStatsCmpmodels.LoginResponsemodels.Usermodels.WebsiteUserException hierarchy. ValidationError is the base; OperationNotAllowedError is raised when required state (url_base, login) is missing.
errors.ValidationErrorerrors.OperationNotAllowedErrorThe distribution on PyPI is umami-analytics, but the import name is umami. Installing umami grabs an unrelated package — always install the analytics client by its full distribution name:
uv pip install umami-analytics # NOT `pip install umami`
import umami # the import name is `umami`
There is no client class — everything is a module-level function called as umami.func(...), and configuration (URL base, website id, hostname, credentials) is stored as module-global state.
Configure once at startup, then send events from anywhere. set_url_base() takes the instance root without the trailing /api, and a trailing slash is stripped for you.
import umami
umami.set_url_base('https://umami.example.com') # required first; validates the http(s) scheme
umami.login('admin', 'super-secret') # only needed for the query/stats calls below
umami.set_website_id('978435e2-7ba1-4337-9860-ec31ece2db60') # default for later calls
umami.set_hostname('example.com') # default hostname for sent events
# Sending events/page views/revenue needs NO login — only url_base + a website_id + hostname.
umami.new_event(event_name='checkout-completed', url='/checkout', custom_data={'plan': 'pro'})
umami.new_revenue_event(revenue=19.99, currency='USD', event_name='checkout-cart', url='/checkout')
umami.new_page_view(page_title='Home', url='/')
Login IS required for the read-back calls: websites(), website_stats(), active_users(), and verify_token(). Sending functions never require it.
Two authentication modes, and you pick exactly one:
set_url_base(...) then login(username, password). Calls carry Authorization: Bearer <token>.set_cloud_api_key(key, region=None) (region is 'us', 'eu', or None). No set_url_base() or login() needed; data calls route to https://api.umami.is/v1 with an x-umami-api-key header and events go to https://cloud.umami.is/api/send.They do not mix. Calling login() while a Cloud API key is set raises OperationNotAllowedError — call clear_cloud_api_key() first to go back to token mode.
Nearly every network operation has an identically-signed _async twin: new_event / new_event_async, website_stats / website_stats_async, login / login_async, and so on. The config setters (set_url_base, set_website_id, set_hostname, enable, disable) are sync-only — there is no set_url_base_async.
disable() does not just skip network — the new_* functions still validate their inputs, then early-return an empty dict {} without any HTTP call. enable() (the default) turns them back on. Query and auth functions ignore this flag and always run.
umami.disable() # e.g. in tests / local dev
umami.new_event(event_name='x', url='/') # validates args, returns {}, sends nothing
iddistinct_id (accepted by new_event, new_revenue_event, new_page_view) is sent as the event payload's id field for logged-in-user attribution. It accepts a str or int only; blank/whitespace values are ignored (no id sent), and a bool (or any other type) raises ValidationError.
umami.errors.OperationNotAllowedError — required state is missing (no url_base/Cloud key, or a query call before login()). It subclasses ValidationError.umami.errors.ValidationError — bad input (empty/non-http url, negative or non-numeric revenue, empty currency, invalid distinct_id, missing hostname/website_id).httpx.HTTPStatusError — a non-2xx server response (the SDK calls raise_for_status()). Note verify_token() and heartbeat() are the exceptions: they never raise and return bool.It covers config, auth, sending events/page views/revenue, listing websites, summarized website_stats, and active_users. For everything else — reports (funnel/attribution/journey/retention/revenue), sessions, event-data, metrics/pageview series, realtime, teams, users, links, pixels, shares — call the Umami HTTP API directly with the token you already hold. Two API gotchas the wrapper hides but direct calls do not:
startAt/endAt as Unix milliseconds; POST /api/reports/* take startDate/endDate as ISO 8601 strings inside parameters.url is now path, and host is now hostname. (In website_stats(...) you still pass url=/host= kwargs; the SDK maps them to path/hostname for you.)The companion agent reference guide documents the complete REST surface.
Every page on the documentation site has a plain-Markdown twin: swap the .html extension for .md to get token-efficient source without the site chrome. For example https://mkennedy.codes/docs/umami-python/reference/new_event.html is also available at https://mkennedy.codes/docs/umami-python/reference/new_event.md. Prefer the .md form when reading these docs programmatically.