MyClub/DOCS/Umami-docs.md

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 <token>. 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 <token>"

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

ok

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

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

ok

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

Sample response

ok


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

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

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

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": 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 
  }
]

x: Unique value, depending on metric type (url | referrer | browser | os | device | country | event).
y: Number of visitors.


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

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
currency : (string)
Request body

{
    "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 : (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

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

ok


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:

<button id="signup-button">Sign up</button>

Add a data property with the following format:

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

So your button element would now look like this:

<button id="signup-button" data-umami-event="Signup button">Sign up</button>

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.