Skills

A skill is a package of structured files that teaches an AI coding agent how to work with a specific tool or framework. The skill below was generated by Great Docs from this project’s documentation. Install it in your agent and it will be able to run commands, edit configuration, write content, and troubleshoot problems without step-by-step guidance from you.

Any agent — install with npx:

npx skills add https://mkennedy.codes/docs/umami-python/

Codex / OpenCode

Tell the agent:
Fetch the skill file at https://mkennedy.codes/docs/umami-python/skill.md and follow the instructions.

Manual — download the skill file:

curl -O https://mkennedy.codes/docs/umami-python/skill.md

Or browse the SKILL.md file.

SKILL.md

---
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

Umami Analytics Client for Python

## Installation

```bash
pip install umami
```

## API overview

### 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`
- `models.Website`
- `models.WebsiteStats`
- `models.WebsiteStatsCmp`
- `models.LoginResponse`
- `models.User`
- `models.WebsiteUser`

### Errors

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

- `errors.ValidationError`
- `errors.OperationNotAllowedError`

## Resources

- [Full documentation](https://mkennedy.codes/docs/umami-python/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/mikeckennedy/umami-python)