MyClub/DOCS/Umami-docs.md at 3ce26509522d780bac1348874fecb3d89f59ff3c

TDvorak/MyClub

Fork 0

mirror of https://github.com/Dvorinka/MyClubServer.git synced 2026-06-03 18:22:57 +00:00

Files

T

Tomáš Dvořák 12cba639b9 upload

2025-10-16 13:32:05 +02:00

41 KiB

Raw Blame History

Getting started Authentication The following authentication method is only for self-hosted Umami. For Umami Cloud, you simply need to generate an API key.

POST /api/auth/login First you need to get a token in order to make API requests. You need to make a POST request to the /api/auth/login endpoint with the following data:

{ "username": "your-username", "password": "your-password" }

If successful you should get a response like the following:

{ "token": "eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A", "user": { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "username": "admin", "role": "admin", "createdAt": "2000-00-00T00:00:00.000Z", "isAdmin": true } }

Save the token value and send an Authorization header with all your data requests with the value Bearer . Your request header should look something like this:

Authorization: Bearer eyTMjU2IiwiY...4Q0JDLUhWxnIjoiUE_A

For example, with curl it would look like this:

curl https://{yourserver}/api/websites -H "Accept: application/json" -H "Authorization: Bearer "

The authorization token is expected with every API call that requires permissions.

POST /api/auth/verify You can verify if the token is still valid.

Sample response

{ "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "username": "admin", "role": "admin", "createdAt": "2000-00-00T00:00:00.000Z", "isAdmin": true }

Getting started Sending stats POST /api/send To register an event, you need to send a POST to /api/send with the following data:

For Umami Cloud send a POST to https://cloud.umami.is/api/send.

Parameters

payload

hostname: (string) Name of host. language: (string) Language of visitor (ex. "en-US") referrer: (string) Referrer URL. screen: (string) Screen resolution (ex. "1920x1080") title: (string) Page title. url: (string) Page URL. website: (string) Website ID. name: (string) Name of the event. data: (object | optional) Additional data for the event. type: (string) event is currently the only type available.

Sample payload

{ "payload": { "hostname": "your-hostname", "language": "en-US", "referrer": "", "screen": "1920x1080", "title": "dashboard", "url": "/", "website": "your-website-id", "name": "event-name", "data": { "foo": "bar" } }, "type": "event" }

Note, for /api/send requests you do not need to send an authentication token.

Also, you need to send a proper User-Agent HTTP header or your request won't be registered.

Programmatically

You can generate most of these values programmatically with JavaScript using the browser APIs. For example:

const data = { payload: { hostname: window.location.hostname, language: navigator.language, referrer: document.referrer, screen: ${window.screen.width}x${window.screen.height}, title: document.title, url: window.location.pathname, website: 'your-website-id', name: 'event-name', }, type: 'event', };

Endpoints Users Operations around User management.

Endpoints

POST /api/users GET /api/admin/users POST /api/users/:userId GET /api/users/:userId DELETE /api/users/:userId GET /api/users/:userId/websites GET /api/users/:userId/teams

POST /api/users Creates a user.

Parameters

username: (string) The user's username. password: (string) The user's password. role: (string) Choose from admin | user | view-only. Request body

{ "username": "admin", "password": "umami", "role": "admin" }

Sample response

{ "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "username": "demo", "role": "user" }

GET /api/admin/users Returns all users. Admin access is required.

Sample response

[ { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "username": "admin", "role": "admin", "createdAt": "0000-00-00T00:00:00.000Z" } ]

GET /api/users/:userId Gets a user by ID.

Sample response

{ "username" : "xxxxxxxxxxx", "id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "role" : "user", "createdAt" : "0000-00-00T00:00:00.000Z" }

POST /api/users/:userId Updates a user.

Parameters

username: (optional string) The user's username. password: (optional string) The user's password. role: (optional string) Select from admin, user, view-only. Request body

{ "username": "admin", "password": "umami", "role": "admin" }

Sample response

{ "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "username": "admin", "role": "admin", "createdAt": "0000-00-00T00:00:00.000Z" }

DELETE /api/users/:userId Deletes a user.

Sample response

GET /api/users/:userId/websites Gets all websites that belong to a user.

Parameters

query: (optional string) Search text. page: (optional number, default 1) Determines page. pageSize: (optional string) Determines how many results to return. orderBy: (optional string, default name) Order by column name. Sample response

{ "data": [ { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "updatedAt": "0000-00-00T00:00:00.00Z", "user": { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "username": "xxxxx" }, "domain": "xxxxxxx", "teamId": null, "resetAt": null, "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "createdBy": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "shareId": "xxxxxxxxxxxxx", "createdAt": "0000-00-00T00:00:00.00Z", "name": "xxxxx", "deletedAt": null } ], "orderBy": "name", "count": 3, "pageSize": 10, "page": 1 }

GET /api/users/:userId/teams Gets all teams that belong to a user.

Parameters

query: (string | optional) Search text. page: (number | optional, default 1) Determines page. pageSize: (string | optional) Determines how many results to return. orderBy: (string | optional, default name) Order by column name. Sample response

{ "data": [ { "_count": { "website": 0, "teamUser": 1 }, "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "logoUrl": null, "deletedAt": null, "teamUser": [ { "teamId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "role": "team-owner", "updatedAt": "0000-00-00T00:00:00.00Z", "createdAt": "0000-00-00T00:00:00.00Z", "user": { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "username": "xxxxx" } } ], "accessCode": "team_xxxxxxxxxxx", "createdAt": "0000-00-00T00:00:00.00Z", "updatedAt": "0000-00-00T00:00:00.00Z", "name": "xxxxxx" } ], "count": 8, "pageSize": 10, "page": 1 }

Endpoints Events Operations around Events and Event data.

Endpoints

GET /api/websites/:websiteId/events GET /api/websites/:websiteId/event-data/events GET /api/websites/:websiteId/event-data/fields GET /api/websites/:websiteId/event-data/values GET /api/websites/:websiteId/event-data/stats

GET /api/websites/:websiteId/events Gets website event details within a given time range.

Parameters

startAt: Timestamp (in ms) of starting date. endAt: Timestamp (in ms) of end date. query: (string | string) Search text. page: (number | optional, default 1) Determines page. pageSize: (string | optional) Determines how many results to return. orderBy: (string | optional) Order by column name. Sample response

{ "data": [ { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "createdAt": "0000-00-00T00:00:00Z", "urlPath": "/docs/api/authentication", "urlQuery": "", "referrerPath": "/docs/api", "referrerQuery": "", "referrerDomain": "", "pageTitle": "Overview – Umami", "eventType": 1, "eventName": "" }, { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "createdAt": "0000-00-00T00:00:00Z", "urlPath": "/", "urlQuery": "utm_source=apollo&utm_medium=outbound-email&utm_campaign=founders", "referrerPath": "", "referrerQuery": "", "referrerDomain": "", "pageTitle": "Umami", "eventType": 1, "eventName": "" } ], "count": 1000, "page": 1, "pageSize": 20 }

GET /api/websites/:websiteId/event-data/events Gets event data names, properties, and counts

Parameters

startAt: Timestamp (in ms) of starting date. endAt: Timestamp (in ms) of end date. event: (optional) Event name filter. Sample response

[ { "eventName": "button-click", "propertyName": "id", "dataType": 1, "total": 4 }, { "eventName": "button-click", "propertyName": "name", "dataType": 1, "total": 4 }, { "eventName": "track-product", "propertyName": "price", "dataType": 2, "total": 2 } ]

GET /api/websites/:websiteId/event-data/fields Gets event data property and value counts within a given time range.

Parameters

websiteId: (uuid) Website key identifier. startAt: Timestamp (in ms) of starting date. endAt: Timestamp (in ms) of end date. Sample response

[ { "propertyName": "age", "dataType": 2, "value": "33", "total": 1 }, { "propertyName": "age", "dataType": 2, "value": "31", "total": 4 }, { "propertyName": "gender", "dataType": 1, "value": "female", "total": 4 }, { "propertyName": "gender", "dataType": 1, "value": "male", "total": 1 } ]

GET /api/websites/:websiteId/event-data/values Gets event data counts for a given event and property

Parameters

startAt: Timestamp (in ms) of starting date. endAt: Timestamp (in ms) of end date. eventName: Event name. propertyName: Property name. Sample response

[ { "value": "female", "total": 4 }, { "value": "male", "total": 1 } ]

GET /api/websites/:websiteId/event-data/stats Gets summarized website events, fields, and records within a given time range.

Parameters

startAt: Timestamp (in ms) of starting date. endAt: Timestamp (in ms) of end date. Sample response

[ { "events": 16, "fields": 13, "records": 26 } ]

Endpoints Sessions Operations around Sessions and Session data.

Endpoints

GET /api/websites/:websiteId/sessions GET /api/websites/:websiteId/sessions/stats GET /api/websites/:websiteId/sessions/:sessionId GET /api/websites/:websiteId/sessions/:sessionId/activity GET /api/websites/:websiteId/sessions/:sessionId/properties GET /api/websites/:websiteId/session-data/properties GET /api/websites/:websiteId/session-data/values GET /api/websites/:websiteId/sessions/weekly

GET /api/websites/:websiteId/sessions Gets website session details within a given time range.

Parameters

startAt: Timestamp (in ms) of starting date. endAt: Timestamp (in ms) of end date. query: (optional string) Search text. page: (optional number, default 1) Determines page. pageSize: (optional string) Determines how many results to return. orderBy: (optional string) Order by column name. Sample response

{ "data": [ { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "createdAt": "0000-00-00T00:00:00Z", "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "lastAt": "0000-00-00T00:00:00Z", "screen": "1920x1080", "hostname": "example.com", "visits": 1, "os": "xxxxx", "browser": "xxxxxx", "language": "xx-xx", "region": "xx-xx", "city": "xxxx", "firstAt": "0000-00-00T00:00:00Z", "device": "desktop", "country": "US", "views": 0 } ], "count": 11, "pageSize": 10, "page": 1 }

GET /api/websites/:websiteId/sessions/stats Gets summarized website session statistics.

Parameters

startAt: Timestamp (in ms) of starting date. endAt: Timestamp (in ms) of end date. url: (optional) Name of URL. referrer: (optional) Name of referrer. title: (optional) Name of page title. query: (optional) Name of query. event: (optional) Name of event. host: (optional) Name of hostname. os: (optional) Name of operating system. browser: (optional) Name of browser. device: (optional) Name of device (ex. Mobile) country: (optional) Name of country. region: (optional) Name of region/state/province. city: (optional) Name of city. Sample response

{ "pageviews" : { "value" : 0 }, "visitors" : { "value" : 11 }, "visits" : { "value" : 12 }, "countries" : { "value" : 2 }, "events" : { "value" : 12 } }

pageviews: Pages hits visitors: Number of unique visitors visits: Number of sessions countries: Number of unique countries events: Number of custom events GET /api/websites/:websiteId/sessions/:sessionId Gets session details for a individual session

Parameters

None

Sample response

URL: https://umami.mydomain.com/api/websites/86d4095c-a2a8-4fc8-9521-103e858e2b41/sessions/a35fe227-2fe9-5147-85a0-15f0fd48faed

{ "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "hostname": "umami.is", "browser": "ios", "os": "iOS", "device": "mobile", "screen": "390x844", "language": "en-US", "country": "US", "subdivision1": "US-IN", "city": "Bloomington", "firstAt": "2024-09-09T18:12:01Z", "lastAt": "2024-09-09T18:12:08Z", "visits": 1, "views": 3, "events": 0, "totaltime": 7 }

GET /api/websites/:websiteId/sessions/:sessionId/activity Gets session activity for a individual session

Parameters

startAt: Timestamp (in ms) of starting date. endAt: Timestamp (in ms) of end date. Sample response

[ { "eventType" : 1, "urlQuery" : "", "urlPath" : "/", "eventName" : "", "createdAt" : "0000-00-00T00:00:00Z", "referrerDomain" : "", "eventId" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "visitId" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }, { "eventType" : 1, "urlQuery" : "", "urlPath" : "/", "eventName" : "", "createdAt" : "0000-00-00T00:00:00Z", "referrerDomain" : "", "eventId" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "visitId" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ]

GET /api/websites/:websiteId/sessions/:sessionId/properties Gets session properties for a individual session

Sample response

URL: https://umami.mydomain.com/api/websites/86d4095c-a2a8-4fc8-9521-103e858e2b41/sessions/a35fe227-2fe9-5147-85a0-15f0fd48faed/properties

[ { "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "dataKey": "email", "dataType": 1, "stringValue": "xxxx@xxxx.xxx", "numberValue": null, "dateValue": null, "createdAt": "0000-00-00T00:00:00Z" }, { "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "sessionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "dataKey": "name", "dataType": 1, "stringValue": "xxxx xxxxx", "numberValue": null, "dateValue": null, "createdAt": "0000-00-00T00:00:00Z" } ]

GET /api/websites/:websiteId/session-data/properties Gets session data counts by property name

Parameters

startAt: Timestamp (in ms) of starting date. endAt: Timestamp (in ms) of end date. Sample response

[ { "propertyName": "id", "total": 1039 }, { "propertyName": "region", "total": 1039 }, { "propertyName": "name", "total": 1039 }, { "propertyName": "email", "total": 1039 } ]

GET /api/websites/:websiteId/session-data/values Gets session data counts for a given property

Parameters

startAt: Timestamp (in ms) of starting date. endAt: Timestamp (in ms) of end date. propertyName: Property name. Sample response

[ { "value": "EU", "total": 609 }, { "value": "US", "total": 431 } ]

GET /api/websites/:websiteId/sessions/weekly Get collected count of sessions by hour of weekday.

Parameters

startAt: (number) Timestamp (in ms) of start date. endAt: (number) Timestamp (in ms) of end date. timezone: (string) Timezone. Sample response

[ [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], ]

Endpoints Websites Operations around Website management and statistics.

Endpoints

GET /api/websites POST /api/websites GET /api/websites/:websiteId POST /api/websites/:websiteId DELETE /api/websites/:websiteId POST /api/websites/:websiteId/reset

GET /api/websites Returns all tracked websites.

Parameters

{ "data": [ { "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "Example", "domain": "example.com", "shareId": null, "resetAt": null, "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "teamId": null, "createdBy": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "createdAt": "0000-00-00T00:00:00.000Z", "updatedAt": "0000-00-00T00:00:00.000Z", "deletedAt": null, "user": { "username": "xxxxxxx@xxxx.xxxx", "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } } ], "count": 2, "page": 1, "pageSize": 10, "orderBy": "name" }

POST /api/websites Creates a website.

Parameters

domain: (string) The full domain of the tracked website. name: (string) The name of the website in Umami. shareId: (string | optional) A unique string to enable a share url. Set null to unshare. teamId: (string | optional) The ID of the team the website will be created under. Request body

{ "name": "Test", "domain": "example.com" }

Sample response

{ "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "Test", "domain": "example.com", "shareId": null, "resetAt": null, "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "teamId": null, "createdBy": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "createdAt": "0000-00-00T00:00:00.000Z", "updatedAt": "0000-00-00T00:00:00.000Z", "deletedAt": null }

GET /api/websites/:websiteId Gets a website by ID.

Sample response

{ "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "Example", "domain": "example.com", "shareId": null, "resetAt": null, "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "createdAt": "0000-00-00T00:00:00.000Z", "updatedAt": null, "deletedAt": null }

POST /api/websites/:websiteId Updates a website.

Parameters

name: (string) The name of the website in Umami. domain: (string) The full domain of the tracked website. shareId: (string | optional) A unique string to enable a share url. Set null to unshare. Request body

{ "name": "Test", "domain": "domain.com" }

Sample response

{ "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "Test", "domain": "domain.com", "shareId": null, "resetAt": null, "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "teamId": null, "createdBy": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "createdAt": "0000-00-00T00:00:00.000Z", "updatedAt": "0000-00-00T00:00:00.000Z", "deletedAt": null }

DELETE /api/websites/:websiteId Deletes a website.

Sample response

POST /api/websites/:websiteId/reset Resets a website by removing all data related to the website.

Sample response

Endpoints Website statistics Operations around Website statistics.

Endpoints

GET /api/websites/:websiteId/active GET /api/websites/:websiteId/events GET /api/websites/:websiteId/pageviews GET /api/websites/:websiteId/metrics GET /api/websites/:websiteId/stats

Unit Parameter

The unit parameter buckets the data returned. The unit is automatically converted to the next largest applicable time unit if the maximum is exceeded.

minute: Up to 60 minutes. hour: Up to 48 hours. day: Up to 12 months. month: No limit. year: No limit. GET /api/websites/:websiteId/active Gets the number of active users on a website.

Sample response

{ "visitors": 5 }

visitors: Number of unique visitors within the last 5 minutes GET /api/websites/:websiteId/events/series Gets events within a given time range.

Parameters

startAt: Timestamp (in ms) of starting date. endAt: Timestamp (in ms) of end date. unit: Time unit (year | month | hour | day). timezone: Timezone (ex. America/Los_Angeles). url: (optional) Name of URL. referrer: (optional) Name of referrer. title: (optional) Name of page title. host: (optional) Name of hostname. os: (optional) Name of operating system. browser: (optional) Name of browser. device: (optional) Name of device (ex. Mobile) country: (optional) Name of country. region: (optional) Name of region/state/province. city: (optional) Name of city. Sample response

[ { "x": "live-demo-button", "t": "2023-04-12T22:00:00Z", "y": 1 }, { "x": "get-started-button", "t": "2023-04-12T22:00:00Z", "y": 5 }, { "x": "get-started-button", "t": "2023-04-12T23:00:00Z", "y": 4 }, { "x": "live-demo-button", "t": "2023-04-12T23:00:00Z", "y": 4 }, { "x": "social-Discord", "t": "2023-04-13T00:00:00Z", "y": 1 } ]

x: Event name. t: Timestamp. y: Number of events. GET /api/websites/:websiteId/pageviews Gets pageviews within a given time range.

Parameters

{ "pageviews": [ { "x": "2020-04-20 01:00:00", "y": 3 }, { "x": "2020-04-20 02:00:00", "y": 7 } ], "sessions": [ { "x": "2020-04-20 01:00:00", "y": 2 }, { "x": "2020-04-20 02:00:00", "y": 4 } ] }

x: Timestamp. y: Number of visitors. GET /api/websites/:websiteId/stats Gets summarized website statistics.

Parameters

{ "pageviews": { "value": 3018, "prev": 3508 }, "visitors": { "value": 847, "prev": 910 }, "visits": { "value": 984, "prev": 1080 }, "bounces": { "value": 537, "prev": 628 }, "totaltime": { "value": 150492, "prev": 164713 } }

pageviews: Pages hits visitors: Number of unique visitors visits: Number of sessions bounces: Number of visitors who only visit a single page totaltime: Time spent on the website GET /api/websites/:websiteId/metrics Gets metrics for a given time range.

Parameters

startAt: Timestamp (in ms) of starting date. endAt: Timestamp (in ms) of end date. type: Metrics type (url | referrer | browser | os | device | country | event). url: (optional) Name of URL. referrer: (optional) Name of referrer. title: (optional) Name of page title. query: (optional) Name of query. host: (optional) Name of hostname. os: (optional) Name of operating system. browser: (optional) Name of browser. device: (optional) Name of device (ex. Mobile) country: (optional) Name of country. region: (optional) Name of region/state/province. city: (optional) Name of city. language: (optional) Name of language. event: (optional) Name of event. limit: (optional, default 500) Number of events returned. Sample response

[ { "x": "/", "y": 46 }, { "x": "/docs", "y": 17 }, { "x": "/download", "y": 14 } ]

Endpoints Realtime Realtime data for your website.

Endpoints

GET /api/realtime/:websiteId

GET /api/realtime/:websiteId Creates a user.

Parameters

startAt: (number) Timestamp (in ms) of start date. endAt: (number) Timestamp (in ms) of end date. timezone: (string) Timezone. Sample response

{ "urls" : { "/" : 1, "/contact" : 2, }, "countries" : { "PL" : 2, "DE" : 5 }, "events" : [ { "__type" : "event", "os" : "xxxx", "device" : "xxxx", "country" : "xx", "sessionId" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "eventName" : "xxx-xxx-xxx-button", "browser" : "xxxxx", "createdAt" : "0000-00-00T00:00:00Z", "urlPath" : "x", "referrerDomain" : "" }, ], "series" : { "views" : [ { "x" : "0000-00-00T00:00:00Z", "y" : 3 }, { "x" : "0000-00-00T00:00:00Z", "y" : 4 } ], "visitors" : [ { "x" : "0000-00-00T00:00:00Z", "y" : 2 }, { "x" : "0000-00-00T00:00:00Z", "y" : 4 } ] }, "referrers" : { "umami.nuxt.dev" : 2, "umami.is" : 33, }, "totals" : { "visitors" : 60, "views" : 79, "events" : 19, "countries" : 22 }, "timestamp" : 1750970573667 }

Endpoints Reports Using reports throught the api.

Endpoints

GET /api/reports GET /api/reports/:reportId GET /api/reports/revenue POST /api/reports/utm POST /api/reports/revenue POST /api/reports/journey POST /api/reports/retention POST /api/reports/insights POST /api/reports/goals POST /api/reports/funnel POST /api/reports/attribution DELETE /api/reports/:reportId

GET /api/reports Get all reports your personal reports.

Parameters

websiteId : (string | optional) Filter for website. Sample response

{ "data" : [ { "userId" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "parameters" : "{"fields":[{"name":"url","type":"string","label":"URL"}],"filters":[],"websiteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","dateRange":{"startDate":"0000-00-00T00:00:00.000Z","endDate":"0000-00-00T00:00:00.000Z","unit":"day","offset":0,"num":90,"value":"90day"}}", "createdAt" : "0000-00-00T00:00:00.000Z", "id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "website" : { "domain" : "example.com" }, "updatedAt" : "0000-00-00T00:00:00.000Z", "type" : "insights", "websiteId" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name" : "Insights", "description" : "" } ], "count" : 1, "pageSize" : 10, "page" : 1 }

GET /api/reports/:reportId Get report details by id

Sample response

{ "userId" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "parameters" : { "fields" : [ { "name" : "url", "type" : "string", "label" : "URL" } ], "dateRange" : { "num" : 90, "value" : "90day", "startDate" : "0000-00-00T00:00:00.000Z", "endDate" : "0000-00-00T00:00:00.000Z", "unit" : "day", "offset" : 0 }, "filters" : [

],
"websiteId" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

}, "createdAt" : "0000-00-00T00:00:00.000Z", "id" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "updatedAt" : "0000-00-00T00:00:00.000Z", "type" : "insights", "websiteId" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name" : "Insights", "description" : "" }

GET /api/reports/revenue Get currency for given range. Needed for Revenue and optional in Attribution reports.

Parameters

websiteId : (string) Your website id startDate : (string) Start date formatted (Thu Mar 27 2025 00:00:00 GMT+0100 (Central European Standard Time)) endDate : (string) End date formatted (Tue Jun 24 2025 23:59:59 GMT+0200 (Central European Summer Time)) Sample response

[ { "currency": "EUR" }, { "currency": "FR" }, { "currency": "USD" } ]

POST /api/reports/utm Track your campaigns through UTM parameters.

Parameters

dateRange startDate : (number) Date (in ms) of start date endDate : (number) Date (in ms) of end date num : (number) offset : (number) unit : (string) value : (string) timezone : (string) Timezone websiteId (string) Your website id Request body

{ "websiteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "dateRange":{ "startDate":"2025-05-17T22:00:00.000Z", "endDate":"2025-05-24T21:59:59.999Z", "unit":"day", "offset":0, "num":1, "value":"0week" }, "timezone":"Europe/Berlin" }

Sample response

{ "utm_source" : { "test" : 1 }, "utm_content" : { "email-newsletter-1" : 1124 }, "utm_term" : { "software" : 4 }, "utm_medium" : { "test" : 1 }, "utm_campaign" : { "test" : 1 }, "utm_agid" : { "12345" : 5 }, "utm_banner" : { "12345" : 1 } }

POST /api/reports/revenue Look into your revenue data and how users are spending.

Parameters

{ "websiteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "dateRange":{ "startDate":"2025-05-19T14:00:00.000Z", "endDate":"2025-05-20T13:59:59.999Z", "offset":0, "num":24, "unit":"hour", "value":"24hour" }, "currency":"USD", "timezone":"Europe/Berlin" }

Sample response

{ "chart": [ { "x": "", "t": "2025-05-19T15:00:00Z", "y": 289.94 } ], "country": [ { "name": "DE", "value": 289.94 } ], "total": { "sum": 289.94, "count": 6, "unique_count": 1 }, "table": [ { "currency": "USD", "sum": 289.94, "count": 6, "unique_count": 1 } ] }

POST /api/reports/journey Understand how users nagivate through your website.

Parameters

dateRange startDate : (number) Date (in ms) of start date endDate : (number) Date (in ms) of end date num : (number) offset : (number) unit : (string) value : (string) steps: (number) Number of steps from 3 to 7 timezone : (string) Timezone websiteId : (string) Your website id startStep : (string | optional) endStep : (string | optional) Request body

{ "steps": 5, "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "dateRange": { "startDate": "2025-05-17T22:00:00.000Z", "endDate": "2025-05-24T21:59:59.999Z", "unit": "day", "offset": 0, "num": 1, "value": "0week" }, "timezone": "Europe/Berlin" }

Sample response

[ { "items": ["index.html", "outbound-link-click", null, null], "count": 1 }, { "items": ["/", null], "count": 1 }, { "items": ["index.html", "open-app-store", null], "count": 1 } ]

POST /api/reports/retention Measure your website stickiness by tracking how often users return.

Parameters

{ "dateRange":{ "startDate":"2025-04-30T22:00:00.000Z", "endDate":"2025-05-31T21:59:59.999Z", "value":"range:1746050400000:1748728799999", "offset":0, "unit":"day" }, "websiteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "timezone":"Europe/Berlin" }

Sample response

[ { "date": "2025-05-18T22:00:00Z", "day": 0, "visitors": 1, "returnVisitors": 1, "percentage": 100 }, { "date": "2025-05-19T22:00:00Z", "day": 0, "visitors": 1, "returnVisitors": 1, "percentage": 100 } ]

POST /api/reports/insights Dive deeper into your data by using segments and filters.

Parameters

dateRange startDate : (number) Date (in ms) of start date endDate : (number) Date (in ms) of end date num : (number) offset : (number) unit : (string) value : (string) fields : (array) Minumum one is required. filters : (array) timezone : (string) Timezone websiteId : (string) Your website id Request body

{ "fields":[ { "name":"url", "type":"string", "label":"URL" } ], "filters":[ ], "websiteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",, "dateRange":{ "startDate":"2025-05-17T22:00:00.000Z", "endDate":"2025-05-24T21:59:59.999Z", "unit":"day", "offset":0, "num":1, "value":"0week" }, "timezone":"Europe/Berlin" }

Sample response

[ { "views": 8, "visitors": 3, "visits": 3, "bounces": 1, "totaltime": 242, "country": "US" } ]

POST /api/reports/goals Track your goals for pageviews and events.

Parameters

dateRange startDate : (number) Date (in ms) of start date endDate : (number) Date (in ms) of end date num : (number) offset : (number) unit : (string) value : (string) goals : (array) Minumum two required. timezone : (string) Timezone websiteId : (string) Your website id Request body

{ "goals":[ { "type":"url", "value":"/", "goal":10 } ], "websiteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "dateRange":{ "startDate":"2025-05-17T22:00:00.000Z", "endDate":"2025-05-24T21:59:59.999Z", "unit":"day", "offset":0, "num":1, "value":"0week" }, "timezone":"Europe/Berlin" }

Sample response

[ { "type": "url", "value": "/", "goal": 10, "result": 10 } ]

POST /api/reports/funnel Understand the conversion and drop-off rate of users.

Parameters

dateRange startDate : (number) Date (in ms) of start date endDate : (number) Date (in ms) of end date num : (number) offset : (number) unit : (string) value : (string) steps : (array) Minumum two required. timezone : (string) Timezone websiteId : (string) Your website id window : (number) Request body

{ "window":60, "steps":[ { "type":"url", "value":"/" }, { "type":"url", "value":"/contact" } ], "websiteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "dateRange":{ "startDate":"2025-05-13T22:00:00.000Z", "endDate":"2025-05-20T21:59:59.999Z", "unit":"day", "offset":0, "num":7, "value":"7day" }, "timezone":"Europe/Berlin" }

Sample response

[ { "type": "url", "value": "/", "visitors": 1, "previous": 0, "dropped": 0, "dropoff": null, "remaining": 1 } ]

POST /api/reports/attribution See how users engage with your marketing and what drives conversions.

Parameters

dateRange startDate : (number) Date (in ms) of start date endDate : (number) Date (in ms) of end date num : (number) offset : (number) unit : (string) value : (string) model : (string) Choose between firstClick and lastClick steps : (array) Only one step. timezone : (string) Timezone websiteId : (string) Your website id Request body

{ "model":"firstClick", "steps":[ { "type":"event", "value":"/" } ], "websiteId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "dateRange":{ "startDate":"2025-05-13T22:00:00.000Z", "endDate":"2025-05-20T21:59:59.999Z", "unit":"day", "offset":0, "num":7, "value":"7day" }, "timezone":"Europe/Berlin" }

Sample response

{ "paidAds" : [ { "name" : "Google", "value" : 129 } ], "referrer" : [ { "name" : "google.com", "value" : 21273 } ], "utm_source" : [ { "name" : "yahoo.de", "value" : 671 } ], "utm_content" : [ { "name" : "info-email-3", "value" : 24 } ], "utm_medium" : [ { "name" : "outbound-email", "value" : 150 } ], "utm_campaign" : [ { "name" : "analytics", "value" : 69 } ], "utm_term" : [ { "name" : "software", "value" : 2 } ], "total" : { "visitors" : 79106, "visits" : 105066, "pageviews" : 136971 } }

DELETE /api/reports/:reportId Delete report with given id.

Sample response

Clients API client Overview Umami API Client is built in TypeScript and contains functions to call every API endpoint available in Umami.

Requirements Node.js version 18.18 or newer Installation npm install @umami/api-client

Configure The following environment variables are required to call your own API.

UMAMI_API_CLIENT_USER_ID UMAMI_API_CLIENT_SECRET UMAMI_API_CLIENT_ENDPOINT

To access Umami Cloud, these environment variables are required.

UMAMI_API_KEY UMAMI_API_CLIENT_ENDPOINT

More details on accessing Umami Cloud can be found under API key.

Usage Import the configured api-client and query using the available class methods.

import { getClient } from '@umami/api-client';

const client = getClient();

const { ok, data, status, error } = await client.getWebsites();

The result will come back in the following format.

{ ok: boolean; status: number; data?: T; error?: any; }

API Client function mapping Me getMe() ⇒ GET /me updateMyPassword(data) ⇒ POST /me/password getMyWebsites() ⇒ GET /me/websites

Users getUsers() ⇒ GET /users createUser(data) ⇒ POST /users getUser(id) ⇒ GET /users/{id} updateUser(id, data) ⇒ POST /users/{id} deleteUser(id) ⇒ DEL /users/{id} getUserWebsites(id) ⇒ GET /users/{id}/websites getUserUsage(id, data) ⇒ GET /users/{id}/usage

Teams getTeams() ⇒ GET /teams createTeam(data) ⇒ POST /teams joinTeam(data) ⇒ POST /teams/join getTeam(id) ⇒ GET /teams/{id} updateTeam(id) ⇒ POST /teams/{id} deleteTeam(id) ⇒ DEL /teams/{id} getTeamUsers(id) ⇒ GET /teams/{id}/users deleteTeamUser(teamId, userId): DEL /teams/{teamId}/users/{userId} getTeamWebsites(id) ⇒ GET /teams/{id}/websites createTeamWebsites(id, data) ⇒ GET /teams/{id}/websites deleteTeamWebsite(teamId, websiteId) ⇒ DEL /teams/{teamId}/websites/{websiteId}

Websites getWebsites() ⇒ GET /websites createWebsite(data) ⇒ POST /websites getWebsite(id) ⇒ GET /websites/{id} updateWebsite(id, data) ⇒ POST /websites/{id} deleteWebsite(id) ⇒ DEL /websites/{id} getWebsiteActive(id) ⇒ GET /websites/{id}/active getWebsiteEvents(id, data) ⇒ GET /websites/{id}/events getWebsiteMetrics(id, data) ⇒ GET /websites/{id}/metrics getWebsitePageviews(id, data) ⇒ GET /websites/{id}/pageviews resetWebsite(id) ⇒ GET /websites/{id}/reset getWebsiteStats(id, data) ⇒ GET /websites/{id}/stats

Event Data getEventDataEvents(id, data) ⇒ GET /event-data/events getEventDataFields(id, data) ⇒ GET /event-data/fields getEventDataStats(id, data) ⇒ GET /event-data/stats

Basics Track events Besides pageviews, Umami is also able to track events that occur on your website. There are two ways to record events in Umami, using the data attributes property or using JavaScript.

Limits Event names are limited to 50 characters. Event data cannot be sent without an event name. Using data attributes To enable events, simply add a special data property to the element you want to track.

For example, you might have a button with the following code:

Add a data property with the following format:

data-umami-event="{event-name}"

So your button element would now look like this:

When the user clicks on this button, Umami will record an event named Signup button.

You can optionally pass along event_data with the data-umami-event-* annotation.

data-umami-event="Signup button" data-umami-event-email="bob@aol.com" data-umami-event-id="123"

The additional properties will result in { email: 'bob@aol.com', id: '123' } being recorded with the Signup button name.

Notes All event data will be saved as a string using this method. If you want to save event data as numeric, dates, booleans, etc. use the JavaScript method below. Other event listeners inside the element will not be triggered. Using JavaScript You can also record events manually using the window.umami object. To accomplish the same thing as the above data-* method, you can do:

const button = document.getElementById('signup-button');

button.onclick = () => umami.track('Signup button');

In this case, Umami will record an event named Signup button.

If you want to record dynamic data, see Tracker functions.

41 KiB Raw Blame History Unescape Escape

41 KiB

Raw Blame History