Posts: Get visitor data via Umami API

Authentication

Umami API requires authentication, which can be done using the user's API key or using the API key from the website share x-umami-share-token.

Getting the User's API Key

Getting API Key for Umami Cloud Users

If you are a Umami Cloud user, you need to generate the API key in the Umami Cloud console.

Umami Cloud API Key Documentation

Getting API Key for Umami Self-Hosted Users

If you are a Umami Self-Hosted user, you need to send the following request body to POST /api/auth/login,

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

If the login is successful, you should receive the following response, note down token.

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

Getting the API Key from the Share Link

After enabling the share link for the website, you will receive a share link, like:

https://u.ksable.top/share/gR1PdRDiutFusWn6

Add api to the beginning of the pathname of the link, like:

https://u.ksable.top/api/share/gR1PdRDiutFusWn6

Then open it, and you will receive the following response, note down token.

{
  "websiteId": "a-b-c-d",
  "token": "a.b.c"
}

Adding Authentication to the Interface

To add authentication to the interface, you need to include the authorization field in the request header, with the value Bearer {token}.

GET /api/*
Authorization: Bearer a.b.c

If you obtained token from the share link, you need to add the x-umami-share-token field in the request header, with the value token.

GET /api/*
x-umami-share-token: a.b.c

Retrieving Visitor Data

API Endpoint

GET /api/websites/:websiteId/stats

Parameters

Example:

GET /api/websites/:websiteId/stats
Authorization: Bearer a.b.c

You will receive the following response,

{
  "pageviews": 15171,
  "visitors": 4415,
  "visits": 5680,
  "bounces": 3567,
  "totaltime": 809968,
  "comparison": {
    "pageviews": 38675,
    "visitors": 10568,
    "visits": 14595,
    "bounces": 9364,
    "totaltime": 2182387
  }
}

Where pageviews is the number of page views, and visitors is the number of unique visitors. Usually, only these two metrics are needed.

Descriptions of some fields are as follows:

{
  "pageviews": {
    "value": 15171
  },
  "visitors": {
    "value": 4415
  },
  "visits": {
    "value": 5680
  },
  "bounces": {
    "value": 3567
  },
  "totaltime": {
    "value": 809968
  }
}

You can add the filters parameter to filter the data as needed. For example, path=/post/bian-jian-tong-guo-api-huo-qu-umami-fang-ke-shu-ju

GET /api/websites/:websiteId/stats?path=/post/bian-jian-tong-guo-api-huo-qu-umami-fang-ke-shu-ju

Will return visitor data for the path /post/bian-jian-tong-guo-api-huo-qu-umami-fang-ke-shu-ju.

References

• Umami API Documentation