Class: Umami::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/umami/client.rb

Overview

The Client class provides methods to interact with the Umami API.

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Client

Initialize a new Umami API client

Parameters:

  • options (Hash) (defaults to: {}) —

    options to create a client with.

Options Hash (options):

  • :uri_base (String) —

    The base URI for the Umami API

  • :request_timeout (Integer) —

    Request timeout in seconds

  • :access_token (String) —

    Access token for authentication

  • :username (String) —

    Username for authentication (only for self-hosted instances)

  • :password (String) —

    Password for authentication (only for self-hosted instances)



19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/umami/client.rb', line 19

def initialize(options = {})
  @config = options[:config] || Umami.configuration
  @config.validate!  # Validate the configuration before using it

  @uri_base = options[:uri_base] || @config.uri_base
  @request_timeout = options[:request_timeout] || @config.request_timeout
  @access_token = options[:access_token] || @config.access_token
  @username = options[:username] || @config.username
  @password = options[:password] || @config.password

  validate_client_options

  authenticate if @access_token.nil?
end

Instance Attribute Details

#request_timeout ⇒ Object (readonly)

Returns the value of attribute request_timeout.



9
10
11
 
# File 'lib/umami/client.rb', line 9

def request_timeout
  @request_timeout
end

#uri_base ⇒ Object (readonly)

Returns the value of attribute uri_base.



9
10
11
 
# File 'lib/umami/client.rb', line 9

def uri_base
  @uri_base
end

Instance Method Details

#add_team_user(team_id, user_id, role) ⇒ Hash

Add a user to a team

Parameters:

  • team_id (String) —

    The team's ID

  • user_id (String) —

    The user's ID

  • role (String) —

    The user's role in the team ('team-manager', 'team-member', or 'team-view-only')

Returns:

  • (Hash) —

    Added team user details

See Also:



334
335
336
 
# File 'lib/umami/client.rb', line 334

def add_team_user(team_id, user_id, role)
  post("/api/teams/#{team_id}/users", { userId: user_id, role: role })
end

#admin_teams(params = {}) ⇒ Hash

Get all teams (admin access required, self-hosted only)

Parameters:

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :search (String) —

    Search text

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page (default: 20)

Returns:

  • (Hash) —

    Paginated list of all teams

See Also:



163
164
165
 
# File 'lib/umami/client.rb', line 163

def admin_teams(params = {})
  get("/api/admin/teams", params)
end

#admin_users(params = {}) ⇒ Hash

Get all users (admin access required, self-hosted only)

Parameters:

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :search (String) —

    Search text

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page (default: 20)

Returns:

  • (Hash) —

    Paginated list of all users

See Also:



139
140
141
 
# File 'lib/umami/client.rb', line 139

def admin_users(params = {})
  get("/api/admin/users", params)
end

#admin_websites(params = {}) ⇒ Hash

Get all websites (admin access required, self-hosted only)

Parameters:

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :search (String) —

    Search text

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page (default: 20)

Returns:

  • (Hash) —

    Paginated list of all websites

See Also:



151
152
153
 
# File 'lib/umami/client.rb', line 151

def admin_websites(params = {})
  get("/api/admin/websites", params)
end

#authenticate ⇒ void

This method returns an undefined value.

Authenticate with the Umami API using username and password

This method is called automatically when initializing the client if an access token is not provided. It sets the @access_token instance variable upon successful authentication.

Raises:

See Also:



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/umami/client.rb', line 66

def authenticate
  raise Umami::AuthenticationError, "Username and password are required for authentication" if @username.nil? || @password.nil?

  response = connection.post("/api/auth/login") do |req|
    req.body = { username: @username, password: @password }.to_json
  end

  data = JSON.parse(response.body)
  @access_token = data["token"]

  # Umami answers a successful login with { "token": ..., "user": ... }
  # (https://umami.is/docs/api/authentication#post-/api/auth/login).
  # A 200 without a token would otherwise produce a client that fails
  # every request with an opaque 401 — fail loudly at the source.
  if @access_token.nil? || @access_token.empty?
    raise Umami::AuthenticationError, "Authentication succeeded but the response carried no token"
  end

  # ⚠️ Load-bearing reset. The login POST above just memoized
  # `@connection` — necessarily WITHOUT an Authorization header, since
  # `@access_token` was still nil when the connection was built, and
  # Faraday bakes headers into the connection at build time. Dropping
  # the memo forces the next request to rebuild the connection, this
  # time with the Bearer token (see #connection). Without this reset,
  # every request after a username/password login fails with 401 —
  # the exact bug shipped in <= 0.2.0 (why token-based auth was the
  # only flow that worked against self-hosted instances).
  @connection = nil
rescue Faraday::Error, JSON::ParserError => e
  raise Umami::AuthenticationError, "Authentication failed: #{e.message}"
end

#cloud? ⇒ Boolean

Check if the client is configured for Umami Cloud

Returns:

  • (Boolean) —

    true if using Umami Cloud, false otherwise



37
38
39
 
# File 'lib/umami/client.rb', line 37

def cloud?
  @uri_base == Umami::Configuration::UMAMI_CLOUD_URL
end

#create_report(params = {}) ⇒ Hash

Create a new report

Parameters:

  • params (Hash) (defaults to: {}) —

    Report parameters

Options Hash (params):

  • :websiteId (String) —

    Website ID (required)

  • :type (String) —

    Report type (required)

  • :name (String) —

    Report name (required)

  • :description (String) —

    Report description

  • :parameters (Hash) —

    Report-specific parameters

Returns:

  • (Hash) —

    Created report details

See Also:



1114
1115
1116
 
# File 'lib/umami/client.rb', line 1114

def create_report(params = {})
  post("/api/reports", params)
end

#create_team(name) ⇒ Hash

Create a new team

Parameters:

  • name (String) —

    The team's name

Returns:

  • (Hash) —

    Created team details

See Also:



260
261
262
 
# File 'lib/umami/client.rb', line 260

def create_team(name)
  post("/api/teams", { name: name })
end

#create_user(username, password, role, id: nil) ⇒ Hash

Create a new user

Parameters:

  • username (String) —

    The user's username

  • password (String) —

    The user's password

  • role (String) —

    The user's role ('admin', 'user', or 'view-only')

  • id (String, nil) (defaults to: nil) —

    Optional UUID to assign to the user

Returns:

  • (Hash) —

    Created user details

See Also:



177
178
179
180
181
 
# File 'lib/umami/client.rb', line 177

def create_user(username, password, role, id: nil)
  params = { username: username, password: password, role: role }
  params[:id] = id if id
  post("/api/users", params)
end

#create_website(params = {}) ⇒ Hash

Create a new website

Parameters:

  • params (Hash) (defaults to: {}) —

    Website parameters

Options Hash (params):

  • :name (String) —

    The name of the website in Umami (required)

  • :domain (String) —

    The full domain of the tracked website (required)

  • :shareId (String) —

    A unique string to enable a share url (optional)

  • :teamId (String) —

    The ID of the team the website will be created under (optional)

  • :id (String) —

    Force a specific UUID for the website (optional)

Returns:

  • (Hash) —

    Created website details

See Also:



407
408
409
 
# File 'lib/umami/client.rb', line 407

def create_website(params = {})
  post("/api/websites", params)
end

#delete_link(link_id) ⇒ Hash

Delete a link

Parameters:

  • link_id (String) —

    The link's ID

Returns:

  • (Hash) —

    Confirmation message

See Also:



1041
1042
1043
 
# File 'lib/umami/client.rb', line 1041

def delete_link(link_id)
  delete("/api/links/#{link_id}")
end

#delete_pixel(pixel_id) ⇒ Hash

Delete a pixel

Parameters:

  • pixel_id (String) —

    The pixel's ID

Returns:

  • (Hash) —

    Confirmation message

See Also:



1085
1086
1087
 
# File 'lib/umami/client.rb', line 1085

def delete_pixel(pixel_id)
  delete("/api/pixels/#{pixel_id}")
end

#delete_report(report_id) ⇒ Hash

Delete a report

Parameters:

  • report_id (String) —

    The report's ID

Returns:

  • (Hash) —

    Confirmation message

See Also:



1145
1146
1147
 
# File 'lib/umami/client.rb', line 1145

def delete_report(report_id)
  delete("/api/reports/#{report_id}")
end

#delete_team(team_id) ⇒ Hash

Delete a team

Parameters:

  • team_id (String) —

    The team's ID

Returns:

  • (Hash) —

    Confirmation message

See Also:



310
311
312
 
# File 'lib/umami/client.rb', line 310

def delete_team(team_id)
  delete("/api/teams/#{team_id}")
end

#delete_team_user(team_id, user_id) ⇒ Hash

Remove a user from a team

Parameters:

  • team_id (String) —

    The team's ID

  • user_id (String) —

    The user's ID

Returns:

  • (Hash) —

    Confirmation message

See Also:



365
366
367
 
# File 'lib/umami/client.rb', line 365

def delete_team_user(team_id, user_id)
  delete("/api/teams/#{team_id}/users/#{user_id}")
end

#delete_user(user_id) ⇒ Hash

Delete a user

Parameters:

  • user_id (String) —

    The user's ID

Returns:

  • (Hash) —

    Confirmation message

See Also:



223
224
225
 
# File 'lib/umami/client.rb', line 223

def delete_user(user_id)
  delete("/api/users/#{user_id}")
end

#delete_website(website_id) ⇒ Hash

Delete a website

Parameters:

  • website_id (String) —

    The website's ID

Returns:

  • (Hash) —

    Confirmation message

See Also:



438
439
440
 
# File 'lib/umami/client.rb', line 438

def delete_website(website_id)
  delete("/api/websites/#{website_id}")
end

#event_data_events(website_id, params = {}) ⇒ Object

Deprecated.

Use #website_event_data_events instead



972
973
974
975
 
# File 'lib/umami/client.rb', line 972

def event_data_events(website_id, params = {})
  warn "[DEPRECATION] `event_data_events` is deprecated. Use `website_event_data_events` instead."
  website_event_data_events(website_id, params)
end

#event_data_fields(website_id, params = {}) ⇒ Object

Deprecated.

Use #website_event_data_fields instead



978
979
980
981
 
# File 'lib/umami/client.rb', line 978

def event_data_fields(website_id, params = {})
  warn "[DEPRECATION] `event_data_fields` is deprecated. Use `website_event_data_fields` instead."
  website_event_data_fields(website_id, params)
end

#event_data_stats(website_id, params = {}) ⇒ Object

Deprecated.

Use #website_event_data_stats instead



984
985
986
987
 
# File 'lib/umami/client.rb', line 984

def event_data_stats(website_id, params = {})
  warn "[DEPRECATION] `event_data_stats` is deprecated. Use `website_event_data_stats` instead."
  website_event_data_stats(website_id, params)
end

#join_team(access_code) ⇒ Hash

Join a team

Parameters:

  • access_code (String) —

    The team's access code

Returns:

  • (Hash) —

    Joined team details

See Also:



280
281
282
 
# File 'lib/umami/client.rb', line 280

def join_team(access_code)
  post("/api/teams/join", { accessCode: access_code })
end

#link(link_id) ⇒ Hash

Get a link by ID

Parameters:

  • link_id (String) —

    The link's ID

Returns:

  • (Hash) —

    Link details

See Also:



1019
1020
1021
 
# File 'lib/umami/client.rb', line 1019

def link(link_id)
  get("/api/links/#{link_id}")
end

#links(params = {}) ⇒ Hash

Get all links

Parameters:

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :search (String) —

    Search text

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page

Returns:

  • (Hash) —

    Paginated list of links

See Also:



1010
1011
1012
 
# File 'lib/umami/client.rb', line 1010

def links(params = {})
  get("/api/links", params)
end

#me ⇒ Hash

Get information about the current authenticated user

Returns:

  • (Hash) —

    Current user information including token, authKey, shareToken, and user details

See Also:



104
105
106
 
# File 'lib/umami/client.rb', line 104

def me
  get("/api/me")
end

#my_teams(params = {}) ⇒ Hash

Get all teams for the current authenticated user

Parameters:

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page

Returns:

  • (Hash) —

    Paginated list of teams with members

See Also:



115
116
117
 
# File 'lib/umami/client.rb', line 115

def my_teams(params = {})
  get("/api/me/teams", params)
end

#my_websites(params = {}) ⇒ Hash

Get all websites for the current authenticated user

Parameters:

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :includeTeams (Boolean) —

    Include websites where user is team owner

Returns:

  • (Hash) —

    Paginated list of websites

See Also:



125
126
127
 
# File 'lib/umami/client.rb', line 125

def my_websites(params = {})
  get("/api/me/websites", params)
end

#pixel(pixel_id) ⇒ Hash

Get a pixel by ID

Parameters:

  • pixel_id (String) —

    The pixel's ID

Returns:

  • (Hash) —

    Pixel details

See Also:



1064
1065
1066
 
# File 'lib/umami/client.rb', line 1064

def pixel(pixel_id)
  get("/api/pixels/#{pixel_id}")
end

#pixels(params = {}) ⇒ Hash

Get all pixels

Parameters:

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :search (String) —

    Search text

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page

Returns:

  • (Hash) —

    Paginated list of pixels

See Also:



1055
1056
1057
 
# File 'lib/umami/client.rb', line 1055

def pixels(params = {})
  get("/api/pixels", params)
end

#realtime(website_id) ⇒ Hash

Get realtime stats for a website (last 30 minutes)

Parameters:

  • website_id (String) —

    The website's ID

Returns:

  • (Hash) —

    Realtime data including countries, urls, referrers, events, series, totals

See Also:



996
997
998
 
# File 'lib/umami/client.rb', line 996

def realtime(website_id)
  get("/api/realtime/#{website_id}")
end

#report(report_id) ⇒ Hash

Get a report by ID

Parameters:

  • report_id (String) —

    The report's ID

Returns:

  • (Hash) —

    Report details

See Also:



1123
1124
1125
 
# File 'lib/umami/client.rb', line 1123

def report(report_id)
  get("/api/reports/#{report_id}")
end

#report_attribution(params = {}) ⇒ Hash

Run an attribution report

Parameters:

  • params (Hash) (defaults to: {}) —

    Report parameters

Options Hash (params):

  • :websiteId (String) —

    Website ID (required)

  • :startDate (String) —

    Start date in ISO 8601 format (required)

  • :endDate (String) —

    End date in ISO 8601 format (required)

  • :model (String) —

    Attribution model ('firstClick' or 'lastClick')

  • :type (String) —

    Attribution type ('path' or 'event')

  • :step (Integer) —

    Step number

  • :filters (Hash) —

    Filter criteria (path, referrer, title, query, browser, os, device, country, region, city, hostname, tag, segment, cohort)

Returns:

  • (Hash) —

    Attribution report data

See Also:



1161
1162
1163
 
# File 'lib/umami/client.rb', line 1161

def report_attribution(params = {})
  post("/api/reports/attribution", params)
end

#report_breakdown(params = {}) ⇒ Hash

Run a breakdown report

Parameters:

  • params (Hash) (defaults to: {}) —

    Report parameters

Options Hash (params):

  • :websiteId (String) —

    Website ID (required)

  • :startDate (String) —

    Start date in ISO 8601 format (required)

  • :endDate (String) —

    End date in ISO 8601 format (required)

  • :fields (Array<String>) —

    Fields to break down by (path, title, query, referrer, browser, os, device, country, region, city, hostname, tag, event)

  • :filters (Hash) —

    Filter criteria (path, referrer, title, query, browser, os, device, country, region, city, hostname, tag, segment, cohort)

Returns:

  • (Hash) —

    Breakdown report data

See Also:



1175
1176
1177
 
# File 'lib/umami/client.rb', line 1175

def report_breakdown(params = {})
  post("/api/reports/breakdown", params)
end

#report_funnel(params = {}) ⇒ Hash

Run a funnel report

Parameters:

  • params (Hash) (defaults to: {}) —

    Report parameters

Options Hash (params):

  • :websiteId (String) —

    Website ID (required)

  • :startDate (String) —

    Start date in ISO 8601 format (required)

  • :endDate (String) —

    End date in ISO 8601 format (required)

  • :steps (Array<Hash>) —

    Funnel steps (minimum 2, each with type and value)

  • :window (Integer) —

    Number of days between steps

  • :filters (Hash) —

    Filter criteria (path, referrer, title, query, browser, os, device, country, region, city, hostname, tag, segment, cohort)

Returns:

  • (Hash) —

    Funnel report data with conversion and drop-off rates

See Also:



1190
1191
1192
 
# File 'lib/umami/client.rb', line 1190

def report_funnel(params = {})
  post("/api/reports/funnel", params)
end

#report_goals(params = {}) ⇒ Hash

Run a goals report

Parameters:

  • params (Hash) (defaults to: {}) —

    Report parameters

Options Hash (params):

  • :websiteId (String) —

    Website ID (required)

  • :startDate (String) —

    Start date in ISO 8601 format (required)

  • :endDate (String) —

    End date in ISO 8601 format (required)

  • :type (String) —

    Goal type ('path' or 'event')

  • :value (String) —

    Goal value

  • :filters (Hash) —

    Filter criteria (path, referrer, title, query, browser, os, device, country, region, city, hostname, tag, segment, cohort)

Returns:

  • (Hash) —

    Goals report data

See Also:



1205
1206
1207
 
# File 'lib/umami/client.rb', line 1205

def report_goals(params = {})
  post("/api/reports/goals", params)
end

#report_journey(params = {}) ⇒ Hash

Run a journey report

Parameters:

  • params (Hash) (defaults to: {}) —

    Report parameters

Options Hash (params):

  • :websiteId (String) —

    Website ID (required)

  • :startDate (String) —

    Start date in ISO 8601 format (required)

  • :endDate (String) —

    End date in ISO 8601 format (required)

  • :steps (Integer) —

    Number of steps (3-7)

  • :startStep (String) —

    Starting step path

  • :endStep (String) —

    Ending step path

  • :filters (Hash) —

    Filter criteria (path, referrer, title, query, browser, os, device, country, region, city, hostname, tag, segment, cohort)

Returns:

  • (Hash) —

    Journey report data showing user navigation paths

See Also:



1221
1222
1223
 
# File 'lib/umami/client.rb', line 1221

def report_journey(params = {})
  post("/api/reports/journey", params)
end

#report_retention(params = {}) ⇒ Hash

Run a retention report

Parameters:

  • params (Hash) (defaults to: {}) —

    Report parameters

Options Hash (params):

  • :websiteId (String) —

    Website ID (required)

  • :startDate (String) —

    Start date in ISO 8601 format (required)

  • :endDate (String) —

    End date in ISO 8601 format (required)

  • :timezone (String) —

    Timezone (e.g., 'America/Los_Angeles') (required)

  • :filters (Hash) —

    Filter criteria (path, referrer, title, query, browser, os, device, country, region, city, hostname, tag, segment, cohort)

Returns:

  • (Hash) —

    Retention report data with day-based return rates

See Also:



1235
1236
1237
 
# File 'lib/umami/client.rb', line 1235

def report_retention(params = {})
  post("/api/reports/retention", params)
end

#report_revenue(params = {}) ⇒ Hash

Run a revenue report

Parameters:

  • params (Hash) (defaults to: {}) —

    Report parameters

Options Hash (params):

  • :websiteId (String) —

    Website ID (required)

  • :startDate (String) —

    Start date in ISO 8601 format (required)

  • :endDate (String) —

    End date in ISO 8601 format (required)

  • :timezone (String) —

    Timezone (e.g., 'America/Los_Angeles') (required)

  • :currency (String) —

    ISO 4217 currency code

  • :filters (Hash) —

    Filter criteria (path, referrer, title, query, browser, os, device, country, region, city, hostname, tag, segment, cohort)

Returns:

  • (Hash) —

    Revenue report data

See Also:



1250
1251
1252
 
# File 'lib/umami/client.rb', line 1250

def report_revenue(params = {})
  post("/api/reports/revenue", params)
end

#report_utm(params = {}) ⇒ Hash

Run a UTM report

Parameters:

  • params (Hash) (defaults to: {}) —

    Report parameters

Options Hash (params):

  • :websiteId (String) —

    Website ID (required)

  • :startDate (String) —

    Start date in ISO 8601 format (required)

  • :endDate (String) —

    End date in ISO 8601 format (required)

  • :filters (Hash) —

    Filter criteria (path, referrer, title, query, browser, os, device, country, region, city, hostname, tag, segment, cohort)

Returns:

  • (Hash) —

    UTM report data with campaign parameter breakdown

See Also:



1263
1264
1265
 
# File 'lib/umami/client.rb', line 1263

def report_utm(params = {})
  post("/api/reports/utm", params)
end

#reports(params = {}) ⇒ Hash

Get all reports

Parameters:

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :websiteId (String) —

    Website ID to filter by

  • :type (String) —

    Report type to filter by ('attribution', 'breakdown', 'funnel', 'goal', 'journey', 'retention', 'revenue', 'utm')

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page

Returns:

  • (Hash) —

    Paginated list of reports

See Also:



1100
1101
1102
 
# File 'lib/umami/client.rb', line 1100

def reports(params = {})
  get("/api/reports", params)
end

#reset_website(website_id) ⇒ Hash

Reset a website's data

Parameters:

  • website_id (String) —

    The website's ID

Returns:

  • (Hash) —

    Confirmation message

See Also:



447
448
449
 
# File 'lib/umami/client.rb', line 447

def reset_website(website_id)
  post("/api/websites/#{website_id}/reset")
end

#self_hosted? ⇒ Boolean

Check if the client is configured for a self-hosted Umami instance

Returns:

  • (Boolean) —

    true if using a self-hosted instance, false otherwise



44
45
46
 
# File 'lib/umami/client.rb', line 44

def self_hosted?
  !cloud?
end

#send_event(payload, user_agent: default_user_agent) ⇒ Hash

Note:

No authentication required. Uses https://cloud.umami.is for Umami Cloud.

Send an event to Umami

This method uses a separate connection that:

  • Does NOT include Authorization header (not required for /api/send)
  • Uses https://cloud.umami.is for Umami Cloud (different from the main API URL)
  • Includes a User-Agent header (mandatory per API docs)

Parameters:

  • payload (Hash) —

    Event payload

  • user_agent (String) (defaults to: default_user_agent) —

    Custom User-Agent header (defaults to "umami-ruby/VERSION")

Options Hash (payload):

  • :hostname (String) —

    Name of host (required)

  • :language (String) —

    Language of visitor (e.g., "en-US")

  • :referrer (String) —

    Referrer URL

  • :screen (String) —

    Screen resolution (e.g., "1920x1080")

  • :title (String) —

    Page title

  • :url (String) —

    Page URL (required)

  • :website (String) —

    Website ID (required)

  • :name (String) —

    Name of the event

  • :tag (String) —

    Additional tag description

  • :id (String) —

    Session identifier

  • :data (Hash) —

    Additional data for the event

Returns:

  • (Hash) —

    Response with cache, sessionId, and visitId

See Also:



1292
1293
1294
 
# File 'lib/umami/client.rb', line 1292

def send_event(payload, user_agent: default_user_agent)
  send_post("/api/send", { type: "event", payload: payload }, user_agent: user_agent)
end

#team(team_id) ⇒ Hash

Get a team by ID

Parameters:

  • team_id (String) —

    The team's ID

Returns:

  • (Hash) —

    Team details

See Also:



289
290
291
 
# File 'lib/umami/client.rb', line 289

def team(team_id)
  get("/api/teams/#{team_id}")
end

#team_user(team_id, user_id) ⇒ Hash

Get a user in a team

Parameters:

  • team_id (String) —

    The team's ID

  • user_id (String) —

    The user's ID

Returns:

  • (Hash) —

    Team user details

See Also:



344
345
346
 
# File 'lib/umami/client.rb', line 344

def team_user(team_id, user_id)
  get("/api/teams/#{team_id}/users/#{user_id}")
end

#team_users(team_id, params = {}) ⇒ Hash

Get all users in a team

Parameters:

  • team_id (String) —

    The team's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :search (String) —

    Search text

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page

Returns:

  • (Hash) —

    Paginated list of team users

See Also:



323
324
325
 
# File 'lib/umami/client.rb', line 323

def team_users(team_id, params = {})
  get("/api/teams/#{team_id}/users", params)
end

#team_websites(team_id, params = {}) ⇒ Hash

Get all websites for a team

Parameters:

  • team_id (String) —

    The team's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :search (String) —

    Search text

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page

Returns:

  • (Hash) —

    Paginated list of team websites

See Also:



378
379
380
 
# File 'lib/umami/client.rb', line 378

def team_websites(team_id, params = {})
  get("/api/teams/#{team_id}/websites", params)
end

#teams(params = {}) ⇒ Hash

Get all teams

Parameters:

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page

Returns:

  • (Hash) —

    Paginated list of teams

See Also:



271
272
273
 
# File 'lib/umami/client.rb', line 271

def teams(params = {})
  get("/api/teams", params)
end

#update_link(link_id, params = {}) ⇒ Hash

Update a link

Parameters:

  • link_id (String) —

    The link's ID

  • params (Hash) (defaults to: {}) —

    Link parameters to update

Options Hash (params):

  • :name (String) —

    Link name

  • :url (String) —

    Destination URL

  • :slug (String) —

    URL slug (minimum 8 characters)

Returns:

  • (Hash) —

    Updated link details

See Also:



1032
1033
1034
 
# File 'lib/umami/client.rb', line 1032

def update_link(link_id, params = {})
  post("/api/links/#{link_id}", params)
end

#update_pixel(pixel_id, params = {}) ⇒ Hash

Update a pixel

Parameters:

  • pixel_id (String) —

    The pixel's ID

  • params (Hash) (defaults to: {}) —

    Pixel parameters to update

Options Hash (params):

  • :name (String) —

    Pixel name

  • :slug (String) —

    URL slug (minimum 8 characters)

Returns:

  • (Hash) —

    Updated pixel details

See Also:



1076
1077
1078
 
# File 'lib/umami/client.rb', line 1076

def update_pixel(pixel_id, params = {})
  post("/api/pixels/#{pixel_id}", params)
end

#update_report(report_id, params = {}) ⇒ Hash

Update a report

Parameters:

  • report_id (String) —

    The report's ID

  • params (Hash) (defaults to: {}) —

    Report parameters to update

Options Hash (params):

  • :name (String) —

    Report name

  • :description (String) —

    Report description

  • :parameters (Hash) —

    Report-specific parameters

Returns:

  • (Hash) —

    Updated report details

See Also:



1136
1137
1138
 
# File 'lib/umami/client.rb', line 1136

def update_report(report_id, params = {})
  post("/api/reports/#{report_id}", params)
end

#update_team(team_id, params = {}) ⇒ Hash

Update a team

Parameters:

  • team_id (String) —

    The team's ID

  • params (Hash) (defaults to: {}) —

    Team parameters to update

Options Hash (params):

  • :name (String) —

    The team's new name

  • :accessCode (String) —

    The team's new access code

Returns:

  • (Hash) —

    Updated team details

See Also:



301
302
303
 
# File 'lib/umami/client.rb', line 301

def update_team(team_id, params = {})
  post("/api/teams/#{team_id}", params)
end

#update_team_user(team_id, user_id, role) ⇒ Hash

Update a user's role in a team

Parameters:

  • team_id (String) —

    The team's ID

  • user_id (String) —

    The user's ID

  • role (String) —

    The user's new role ('team-manager', 'team-member', or 'team-view-only')

Returns:

  • (Hash) —

    Confirmation message

See Also:



355
356
357
 
# File 'lib/umami/client.rb', line 355

def update_team_user(team_id, user_id, role)
  post("/api/teams/#{team_id}/users/#{user_id}", { role: role })
end

#update_user(user_id, params = {}) ⇒ Hash

Update a user

Parameters:

  • user_id (String) —

    The user's ID

  • params (Hash) (defaults to: {}) —

    User parameters to update

Options Hash (params):

  • :username (String) —

    The user's new username

  • :password (String) —

    The user's new password

  • :role (String) —

    The user's new role ('admin', 'user', or 'view-only')

Returns:

  • (Hash) —

    Updated user details

See Also:



214
215
216
 
# File 'lib/umami/client.rb', line 214

def update_user(user_id, params = {})
  post("/api/users/#{user_id}", params)
end

#update_website(website_id, params = {}) ⇒ Hash

Update a website

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Website parameters to update

Options Hash (params):

  • :name (String) —

    The name of the website in Umami (required)

  • :domain (String) —

    The full domain of the tracked website (required)

  • :shareId (String) —

    A unique string to enable a share url

Returns:

  • (Hash) —

    Updated website details

See Also:



429
430
431
 
# File 'lib/umami/client.rb', line 429

def update_website(website_id, params = {})
  post("/api/websites/#{website_id}", params)
end

#user(user_id) ⇒ Hash

Get a user by ID

Parameters:

  • user_id (String) —

    The user's ID

Returns:

  • (Hash) —

    User details

See Also:



201
202
203
 
# File 'lib/umami/client.rb', line 201

def user(user_id)
  get("/api/users/#{user_id}")
end

#user_teams(user_id, params = {}) ⇒ Hash

Get all teams for a user

Parameters:

  • user_id (String) —

    The user's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page

Returns:

  • (Hash) —

    Paginated list of user's teams

See Also:



249
250
251
 
# File 'lib/umami/client.rb', line 249

def user_teams(user_id, params = {})
  get("/api/users/#{user_id}/teams", params)
end

#user_websites(user_id, params = {}) ⇒ Hash

Get all websites for a user

Parameters:

  • user_id (String) —

    The user's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :includeTeams (Boolean) —

    Include team websites

  • :search (String) —

    Search text

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page

Returns:

  • (Hash) —

    Paginated list of user's websites

See Also:



237
238
239
 
# File 'lib/umami/client.rb', line 237

def user_websites(user_id, params = {})
  get("/api/users/#{user_id}/websites", params)
end

#users(params = {}) ⇒ Hash

Deprecated.

Use #admin_users instead

Get all users (admin access required)

Parameters:

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :search (String) —

    Search text

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page (default: 20)

Returns:

  • (Hash) —

    Paginated list of all users

See Also:



192
193
194
 
# File 'lib/umami/client.rb', line 192

def users(params = {})
  admin_users(params)
end

#verify_token ⇒ Hash

Verify the authentication token

Returns:

  • (Hash) —

    Token verification result containing user information

See Also:



52
53
54
 
# File 'lib/umami/client.rb', line 52

def verify_token
  post("/api/auth/verify")
end

#website(website_id) ⇒ Hash

Get a website by ID

Parameters:

  • website_id (String) —

    The website's ID

Returns:

  • (Hash) —

    Website details

See Also:



416
417
418
 
# File 'lib/umami/client.rb', line 416

def website(website_id)
  get("/api/websites/#{website_id}")
end

#website_active_visitors(website_id) ⇒ Hash

Get active visitors for a website (last 5 minutes)

Parameters:

  • website_id (String) —

    The website's ID

Returns:

  • (Hash) —

    Number of active visitors

See Also:



484
485
486
 
# File 'lib/umami/client.rb', line 484

def website_active_visitors(website_id)
  get("/api/websites/#{website_id}/active")
end

#website_event_data(website_id, event_id) ⇒ Array<Hash>

Get event data for an individual event

Parameters:

  • website_id (String) —

    The website's ID

  • event_id (String) —

    The event's ID

Returns:

  • (Array<Hash>) —

    Event data properties

See Also:



832
833
834
 
# File 'lib/umami/client.rb', line 832

def website_event_data(website_id, event_id)
  get("/api/websites/#{website_id}/event-data/#{event_id}")
end

#website_event_data_events(website_id, params = {}) ⇒ Array<Hash>

Get event data names, properties, and counts

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :event (String) —

    Event name filter

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :query (String) —

    Filter by query string

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :hostname (String) —

    Filter by hostname

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Array<Hash>) —

    Event data with eventName, propertyName, dataType, total

See Also:



859
860
861
 
# File 'lib/umami/client.rb', line 859

def website_event_data_events(website_id, params = {})
  get("/api/websites/#{website_id}/event-data/events", params)
end

#website_event_data_fields(website_id, params = {}) ⇒ Array<Hash>

Get event data fields within a time range

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :query (String) —

    Filter by query string

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :hostname (String) —

    Filter by hostname

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Array<Hash>) —

    Event data fields with propertyName, dataType, value, total

See Also:



885
886
887
 
# File 'lib/umami/client.rb', line 885

def website_event_data_fields(website_id, params = {})
  get("/api/websites/#{website_id}/event-data/fields", params)
end

#website_event_data_properties(website_id, params = {}) ⇒ Array<Hash>

Get event name and property counts

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :query (String) —

    Filter by query string

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :hostname (String) —

    Filter by hostname

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Array<Hash>) —

    Event properties with eventName, propertyName, total

See Also:



911
912
913
 
# File 'lib/umami/client.rb', line 911

def website_event_data_properties(website_id, params = {})
  get("/api/websites/#{website_id}/event-data/properties", params)
end

#website_event_data_stats(website_id, params = {}) ⇒ Array<Hash>

Get aggregated event statistics

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :query (String) —

    Filter by query string

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :hostname (String) —

    Filter by hostname

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Array<Hash>) —

    Event stats with events, properties, records counts

See Also:



965
966
967
 
# File 'lib/umami/client.rb', line 965

def website_event_data_stats(website_id, params = {})
  get("/api/websites/#{website_id}/event-data/stats", params)
end

#website_event_data_values(website_id, params = {}) ⇒ Array<Hash>

Get event data value counts for a given event and property

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :event (String) —

    Event name (required)

  • :propertyName (String) —

    Property name (required)

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :query (String) —

    Filter by query string

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :hostname (String) —

    Filter by hostname

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Array<Hash>) —

    Value counts with value and total

See Also:



939
940
941
 
# File 'lib/umami/client.rb', line 939

def website_event_data_values(website_id, params = {})
  get("/api/websites/#{website_id}/event-data/values", params)
end

#website_events(website_id, params = {}) ⇒ Array<Hash>

Get website events within a time range

This method returns event data with optional time-series grouping. For paginated event lists with search, use #website_events_list instead.

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :unit (String) —

    Time unit for grouping ('minute', 'hour', 'day', 'month', 'year')

  • :timezone (String) —

    Timezone (e.g., 'America/Los_Angeles')

Returns:

  • (Array<Hash>) —

    Website events

See Also:



530
531
532
 
# File 'lib/umami/client.rb', line 530

def website_events(website_id, params = {})
  get("/api/websites/#{website_id}/events", params)
end

#website_events_list(website_id, params = {}) ⇒ Hash

Get website event details within a time range (paginated list)

This method returns a paginated list of individual events with full details and supports search and filtering. For time-series grouped event data, use #website_events or #website_events_series instead.

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :search (String) —

    Search text

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page (default: 20)

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :query (String) —

    Filter by query string

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :hostname (String) —

    Filter by hostname

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Hash) —

    Paginated list of events with full event details

See Also:



822
823
824
 
# File 'lib/umami/client.rb', line 822

def website_events_list(website_id, params = {})
  get("/api/websites/#{website_id}/events", params)
end

#website_events_series(website_id, params = {}) ⇒ Array<Hash>

Get website events series within a time range

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :unit (String) —

    Time unit for grouping ('minute', 'hour', 'day', 'month', 'year') (required)

  • :timezone (String) —

    Timezone (e.g., 'America/Los_Angeles')

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :hostname (String) —

    Filter by hostname

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Array<Hash>) —

    Event series with x (event name), t (timestamp), y (count)

See Also:



557
558
559
 
# File 'lib/umami/client.rb', line 557

def website_events_series(website_id, params = {})
  get("/api/websites/#{website_id}/events/series", params)
end

#website_metrics(website_id, params = {}) ⇒ Array<Hash>

Get website metrics

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :type (String) —

    Metrics type (required): 'path', 'entry', 'exit', 'title', 'query', 'referrer', 'channel', 'domain', 'country', 'region', 'city', 'browser', 'os', 'device', 'language', 'screen', 'event', 'hostname', 'tag'

  • :limit (Integer) —

    Number of results to return (default: 500)

  • :offset (Integer) —

    Number of results to skip (default: 0)

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :query (String) —

    Filter by query string

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :language (String) —

    Filter by language

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Array<Hash>) —

    Website metrics with x (value) and y (visitor count)

See Also:



586
587
588
 
# File 'lib/umami/client.rb', line 586

def website_metrics(website_id, params = {})
  get("/api/websites/#{website_id}/metrics", params)
end

#website_metrics_expanded(website_id, params = {}) ⇒ Array<Hash>

Get expanded website metrics with detailed engagement data

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :type (String) —

    Metrics type (required): 'path', 'entry', 'exit', 'title', 'query', 'referrer', 'channel', 'domain', 'country', 'region', 'city', 'browser', 'os', 'device', 'language', 'screen', 'event', 'hostname', 'tag'

  • :limit (Integer) —

    Number of results to return (default: 500)

  • :offset (Integer) —

    Number of results to skip (default: 0)

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :query (String) —

    Filter by query string

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :language (String) —

    Filter by language

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Array<Hash>) —

    Expanded metrics with name, pageviews, visitors, visits, bounces, totaltime

See Also:



615
616
617
 
# File 'lib/umami/client.rb', line 615

def website_metrics_expanded(website_id, params = {})
  get("/api/websites/#{website_id}/metrics/expanded", params)
end

#website_pageviews(website_id, params = {}) ⇒ Hash

Get website pageviews within a time range

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :unit (String) —

    Time unit for grouping ('minute', 'hour', 'day', 'month', 'year') (required)

  • :timezone (String) —

    Timezone (e.g., 'America/Los_Angeles')

  • :compare (String) —

    Comparison mode ('prev' or 'yoy')

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :hostname (String) —

    Filter by hostname

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Hash) —

    Pageviews and sessions arrays with timestamp and count

See Also:



512
513
514
 
# File 'lib/umami/client.rb', line 512

def website_pageviews(website_id, params = {})
  get("/api/websites/#{website_id}/pageviews", params)
end

#website_session(website_id, session_id) ⇒ Hash

Get details for an individual session

Parameters:

  • website_id (String) —

    The website's ID

  • session_id (String) —

    The session's ID

Returns:

  • (Hash) —

    Session details including browser, os, device, visits, views, events, totaltime

See Also:



709
710
711
 
# File 'lib/umami/client.rb', line 709

def website_session(website_id, session_id)
  get("/api/websites/#{website_id}/sessions/#{session_id}")
end

#website_session_activity(website_id, session_id, params = {}) ⇒ Array<Hash>

Get activity for an individual session

Parameters:

  • website_id (String) —

    The website's ID

  • session_id (String) —

    The session's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

Returns:

  • (Array<Hash>) —

    Session activity records

See Also:



722
723
724
 
# File 'lib/umami/client.rb', line 722

def website_session_activity(website_id, session_id, params = {})
  get("/api/websites/#{website_id}/sessions/#{session_id}/activity", params)
end

#website_session_data_properties(website_id, params = {}) ⇒ Array<Hash>

Get session data property counts

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :query (String) —

    Filter by query string

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :hostname (String) —

    Filter by hostname

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Array<Hash>) —

    Property aggregations with propertyName and total

See Also:



758
759
760
 
# File 'lib/umami/client.rb', line 758

def website_session_data_properties(website_id, params = {})
  get("/api/websites/#{website_id}/session-data/properties", params)
end

#website_session_data_values(website_id, params = {}) ⇒ Array<Hash>

Get session data value counts for a property

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :propertyName (String) —

    Property name to query (required)

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :query (String) —

    Filter by query string

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :hostname (String) —

    Filter by hostname

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Array<Hash>) —

    Value aggregations with value and total

See Also:



785
786
787
 
# File 'lib/umami/client.rb', line 785

def website_session_data_values(website_id, params = {})
  get("/api/websites/#{website_id}/session-data/values", params)
end

#website_session_properties(website_id, session_id) ⇒ Array<Hash>

Get properties for an individual session

Parameters:

  • website_id (String) —

    The website's ID

  • session_id (String) —

    The session's ID

Returns:

  • (Array<Hash>) —

    Session properties

See Also:



732
733
734
 
# File 'lib/umami/client.rb', line 732

def website_session_properties(website_id, session_id)
  get("/api/websites/#{website_id}/sessions/#{session_id}/properties")
end

#website_sessions(website_id, params = {}) ⇒ Hash

Get website sessions within a time range

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :search (String) —

    Search text

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page (default: 20)

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :query (String) —

    Filter by query string

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :hostname (String) —

    Filter by hostname

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Hash) —

    Paginated list of sessions

See Also:



646
647
648
 
# File 'lib/umami/client.rb', line 646

def website_sessions(website_id, params = {})
  get("/api/websites/#{website_id}/sessions", params)
end

#website_sessions_stats(website_id, params = {}) ⇒ Hash

Get summarized session statistics

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :query (String) —

    Filter by query string

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :hostname (String) —

    Filter by hostname

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Hash) —

    Session statistics including pageviews, visitors, visits, countries, events

See Also:



672
673
674
 
# File 'lib/umami/client.rb', line 672

def website_sessions_stats(website_id, params = {})
  get("/api/websites/#{website_id}/sessions/stats", params)
end

#website_sessions_weekly(website_id, params = {}) ⇒ Array<Array>

Get session counts by hour of weekday

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :timezone (String) —

    Timezone (e.g., 'America/Los_Angeles') (required)

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :query (String) —

    Filter by query string

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :hostname (String) —

    Filter by hostname

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Array<Array>) —

    7x24 matrix of session counts by weekday and hour

See Also:



699
700
701
 
# File 'lib/umami/client.rb', line 699

def website_sessions_weekly(website_id, params = {})
  get("/api/websites/#{website_id}/sessions/weekly", params)
end

#website_stats(website_id, params = {}) ⇒ Hash

Get website statistics

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date (required)

  • :endAt (Integer) —

    Timestamp (in ms) of end date (required)

  • :path (String) —

    Filter by URL path

  • :referrer (String) —

    Filter by referrer

  • :title (String) —

    Filter by page title

  • :query (String) —

    Filter by query string

  • :os (String) —

    Filter by operating system

  • :browser (String) —

    Filter by browser

  • :device (String) —

    Filter by device type

  • :country (String) —

    Filter by country

  • :region (String) —

    Filter by region/state/province

  • :city (String) —

    Filter by city

  • :hostname (String) —

    Filter by hostname

  • :tag (String) —

    Filter by tag

  • :segment (String) —

    Filter by segment UUID

  • :cohort (String) —

    Filter by cohort UUID

Returns:

  • (Hash) —

    Website statistics including pageviews, visitors, visits, bounces, totaltime

See Also:



475
476
477
 
# File 'lib/umami/client.rb', line 475

def website_stats(website_id, params = {})
  get("/api/websites/#{website_id}/stats", params)
end

#websites(params = {}) ⇒ Hash

Get all websites

Parameters:

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :includeTeams (Boolean) —

    Include websites where user is team owner

  • :search (String) —

    Search text

  • :page (Integer) —

    Page number (default: 1)

  • :pageSize (Integer) —

    Number of results per page

Returns:

  • (Hash) —

    Paginated list of websites

See Also:



393
394
395
 
# File 'lib/umami/client.rb', line 393

def websites(params = {})
  get("/api/websites", params)
end