API Reference

The public umami-analytics surface: configuration, authentication, sending events, and querying stats. Every network operation has a synchronous function and an identically-signed _async twin.

Configuration

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 instance.
set_website_id(): Set the default website ID used for subsequent calls.
set_hostname(): Set the default hostname used when sending events and page views.
set_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 behavior.
enable(): Enable event and page view tracking.
disable(): Disable event and page view tracking.

Authentication

Required 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 token.
login_async(): Log into a self-hosted Umami instance and retrieve a temporary auth token.
is_logged_in(): Whether a credential is currently set locally.
verify_token(): Verify that the currently stored credential is still valid.
verify_token_async(): Verify that the currently stored credential is still valid.

Sending events

Send 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 hostname
new_event_async(): Create a new custom event in Umami for the given website_id and hostname
new_revenue_event(): Create a new revenue event in Umami. This is a convenience wrapper around
new_revenue_event_async(): Create a new revenue event in Umami. This is a convenience wrapper around
new_page_view(): Create a new page view event in Umami for the given website_id and hostname
new_page_view_async(): Create a new page view event in Umami for the given website_id and hostname

Querying stats

Read analytics back out. Requires login (or a Cloud API key).

websites(): All the websites that are registered in your Umami instance.
websites_async(): All the websites that are registered in your Umami instance.
website_stats(): Retrieves the statistics for a specific website over a date range.
website_stats_async(): Retrieves the statistics for a specific website over a date range.
active_users(): Retrieves the number of currently-active visitors for a specific website.
active_users_async(): Retrieves the number of currently-active visitors for a specific website.

Health

Check Umami server connectivity.

heartbeat(): Check whether the configured Umami server is reachable and healthy.
heartbeat_async(): Check whether the configured Umami server is reachable and healthy.

Response models

Pydantic models returned by the query functions.

models.WebsitesResponse: The paged envelope returned by the Umami /api/websites endpoint.
models.Website: A website registered in your Umami instance.
models.WebsiteStats: Aggregate traffic statistics for a website over a time range.
models.WebsiteStatsCmp: Prior-period comparison totals for a website’s statistics.
models.LoginResponse: The result of authenticating against a self-hosted Umami instance.
models.User: An authenticated Umami user account.
models.WebsiteUser: A minimal reference to the user who owns or created a website.

Errors

Exception hierarchy. ValidationError is the base; OperationNotAllowedError is raised when required state (url_base, login) is missing.

errors.ValidationError: Base exception raised when an input or argument fails validation.
errors.OperationNotAllowedError: Raised when the SDK is missing required state for an operation.