User Guide

It is 2:14 in the morning and someone in Lisbon just bought a course. The browser tracker watched them read the description and hit the buy button, and then it lost them. The sale finished in a payment webhook on a server, in Python, with no page and no click to hang a data-umami-event attribute on. The dashboard never finds out.

That gap is the reason this package exists. Umami is very good at watching browsers. Your most valuable events happen somewhere else: a payment provider’s callback, a nightly job that finishes, a mobile app that calls your API. umami-analytics lets the Python code that already knows about those moments report them to Umami, so the sale from Lisbon shows up right next to the page view that led to it.

What it does: send custom events, page views, and revenue to a self-hosted Umami instance or to Umami Cloud, and read back the basic numbers: your websites, page views and visitors over a date range, and how many people are on the site right now. Every network call has a synchronous function and an _async twin, so it fits a Flask view and a FastAPI handler equally well.

What it leaves out, on purpose: the rest of the Umami API. Umami’s API is large because its own dashboard is built on it. This package wraps the parts a backend needs and stops. Reports, sessions, event data, and everything else are one HTTP call away with the token the package already holds, and How it works shows that call.

Where to go next

• Getting started: install, point the package at your instance, send one event, and watch it land in the dashboard. A short read and about ten lines of code.
• Sending events: custom events, page views, revenue, custom data, and distinct_id for tying events to a known user.
• Authentication: self-hosted login versus an Umami Cloud API key, and the answer to when you need either, which surprises most people.
• Querying stats: list websites, pull visitors and page views for a date range, filter them, and count who is on the site this minute.
• Troubleshooting: what each error means and what to do about it, including the case where the event returns 200 and vanishes.
• Testing and CI: keep test runs out of your analytics with disable(), and mock the one HTTP boundary.
• Configuration: every setting, its default, and which calls need it.
• How it works: module-global state, request routing, headers, the two user agents, and what the package leaves out.
• FAQ: short answers to the questions that come up most.

The API Reference documents every public function and model, with the sync and async twins side by side.