Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

[API Key analytics] Integration branch → master (#83726)

Sébastien21613fe65f92
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.edn
index 645a5b7d447..5e8c0273cd9 100644
--- a/.clj-kondo/config/modules/config.edn
+++ b/.clj-kondo/config/modules/config.edn
@@ -182,6 +182,7 @@
metabase.analytics.core
metabase.analytics.event
metabase.analytics.init
+ metabase.analytics.sdk
metabase.analytics.settings}
:uses #{analytics.interface
analytics.internal-stats
@@ -296,16 +297,18 @@
{:team "UX West"
:api #{metabase.api-keys.api
metabase.api-keys.core
- metabase.api-keys.schema}
+ metabase.api-keys.schema
+ metabase.api-keys.usage}
:uses #{api
app-db
events
lib.schema
models
permissions
+ premium-features
users
util}
- :model-exports #{:model/ApiKey}
+ :model-exports #{:model/ApiKey :model/ApiKeyUsageLog}
:model-imports #{:model/User}}
api-routes
@@ -2862,6 +2865,7 @@
metabase.testing-api.init}
:uses #{analytics
api
+ api-keys
app-db
lib
lib.be
@@ -3544,6 +3548,19 @@
premium-features
util}}
+ enterprise/api-keys
+ {:team "UX West"
+ :api #{metabase-enterprise.api-keys.init}
+ :uses #{analytics
+ api-keys
+ metabot
+ premium-features
+ request
+ startup
+ task
+ util}
+ :model-imports #{:model/ApiKeyUsageLog}}
+
enterprise/api-routes
{:team "UX West"
:api #{metabase-enterprise.api-routes.routes}
diff --git a/docs/configuring-metabase/environment-variables.md b/docs/configuring-metabase/environment-variables.md
index 5f67650da1f..c25b7eb20fb 100644
--- a/docs/configuring-metabase/environment-variables.md
+++ b/docs/configuring-metabase/environment-variables.md
@@ -86,7 +86,7 @@ Whether AI features are enabled.
- [Exported as](../installation-and-operation/serialization.md): `ai-usage-max-retention-days`.
- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file.md).
-Number of days to retain rows in the ai_usage_log, metabot_conversation, and metabot_message tables. Minimum value is 30; set to 0 to retain data indefinitely.
+Number of days to retain rows in the ai_usage_log, metabot_conversation, metabot_message, agent_api_call_log, and api_key_usage_log tables. Minimum value is 30; set to 0 to retain data indefinitely.
Sets the maximum number of days Metabase preserves rows for the following application database tables:
@@ -94,6 +94,7 @@ Sets the maximum number of days Metabase preserves rows for the following applic
- `metabot_conversation`
- `metabot_message`
- `agent_api_call_log`
+- `api_key_usage_log`
Once a day, Metabase deletes rows older than this threshold. The minimum value is 30 days (Metabase will treat entered values of 1 to 29 the same as 30).
If set to 0, Metabase will keep all rows. If you don't set this variable, Metabase keeps rows for 180 days.
diff --git a/e2e/test/scenarios/monitor/api-key-usage.cy.spec.ts b/e2e/test/scenarios/monitor/api-key-usage.cy.spec.ts
new file mode 100644
index 00000000000..3afb010e6f0
--- /dev/null
+++ b/e2e/test/scenarios/monitor/api-key-usage.cy.spec.ts
@@ -0,0 +1,120 @@
+const { H } = cy;
+
+import { ADMIN_USER_ID } from "e2e/support/cypress_sample_instance_data";
+
+const API_KEY_USAGE_PATH = "/monitor/api-key-usage";
+const ADMIN_GROUP_ID = 2;
+const SEEDED_KEY_NAME = "e2e_seeded_key";
+const UNUSED_KEY_NAME = "e2e_unused_key";
+const ADMIN_DISPLAY_NAME = "Bobby Tables";
+
+type CreateApiKeyResponse = { id: number };
+
+function seedApiKeyUsage(
+ apiKeyId: number,
+): Cypress.Chainable<Cypress.Response<{ inserted: number }>> {
+ return cy.request("POST", "/api/testing/api-keys/seed-usage", {
+ api_key_id: apiKeyId,
+ user_id: ADMIN_USER_ID,
+ created_by_id: ADMIN_USER_ID,
+ });
+}
+
+function visitApiKeyUsagePage(): void {
+ cy.intercept("GET", "/api/database/13371337/metadata*").as("auditMetadata");
+
+ cy.visit(API_KEY_USAGE_PATH);
+ cy.wait("@auditMetadata");
+}
+
+// The first query against the audit view can take a while to settle locally, so this gates on
+// aria-busy clearing (rather than a network alias, which races against the Usage tab's own chart
+// queries sharing the same /api/dataset endpoint) before asserting on rendered content.
+function eventsTable() {
+ cy.findByTestId("api-key-usage-events-table", { timeout: 20000 }).should(
+ "have.attr",
+ "aria-busy",
+ "false",
+ );
+ return cy.findByTestId("api-key-usage-events-table");
+}
+
+function selectApiKeyFilter(label: string): void {
+ cy.findByTestId("api-key-usage-filter-select").click();
+ H.popover().findByRole("option", { name: label }).click();
+}
+
+// The events table has 11 columns and doesn't fit the default viewport.
+describe("scenarios > monitor > api key usage", { viewportWidth: 1600 }, () => {
+ beforeEach(() => {
+ H.restore();
+ cy.signInAsAdmin();
+ H.activateToken("pro-self-hosted");
+ });
+
+ it("shows seeded usage and lets an admin filter by API key and date", () => {
+ H.createApiKey(SEEDED_KEY_NAME, ADMIN_GROUP_ID).then(
+ ({ body }: { body: CreateApiKeyResponse }) => {
+ seedApiKeyUsage(body.id);
+ },
+ );
+ H.createApiKey(UNUSED_KEY_NAME, ADMIN_GROUP_ID);
+
+ visitApiKeyUsagePage();
+
+ cy.log("The nav item lives directly under Monitor");
+ cy.findByRole("link", { name: "API key usage" }).should("be.visible");
+
+ cy.log("The Usage tab renders with the seeded key (not the empty state)");
+ H.main().within(() => {
+ cy.findByRole("heading", { name: "API key usage" }).should("be.visible");
+ cy.findByText("No API key activity").should("not.exist");
+ cy.findByText(SEEDED_KEY_NAME).should("be.visible");
+ });
+
+ cy.log(
+ "The API key filter scopes the Key activity table, but an unused key still shows its own row",
+ );
+ selectApiKeyFilter(UNUSED_KEY_NAME);
+ H.main().within(() => {
+ cy.findByText("No API key activity").should("not.exist");
+ cy.findByText(UNUSED_KEY_NAME).should("be.visible");
+ cy.findByText(SEEDED_KEY_NAME).should("not.exist");
+ });
+ selectApiKeyFilter("All API keys");
+ H.main().findByText(SEEDED_KEY_NAME).should("be.visible");
+
+ cy.log("The Events tab shows the seeded call, attributed to its creator");
+ H.main().findByRole("link", { name: "Events" }).click();
+ eventsTable().within(() => {
+ cy.findByText("Created by").should("be.visible");
+ cy.findByText(SEEDED_KEY_NAME).should("be.visible");
+ cy.findByText(ADMIN_DISPLAY_NAME).should("be.visible");
+ });
+
+ cy.log(
+ "There's no separate user filter — the API key filter is the primary way to scope the page",
+ );
+ cy.findByTestId("conversation-filters-user-select").should("not.exist");
+
+ cy.log("Filtering by the seeded API key keeps the call");
+ selectApiKeyFilter(SEEDED_KEY_NAME);
+ eventsTable().findByText(SEEDED_KEY_NAME).should("be.visible");
+
+ cy.log(
+ "Filtering by an unused API key shows the events table's own empty state, not the whole page",
+ );
+ selectApiKeyFilter(UNUSED_KEY_NAME);
+ H.main().findByText("No API key activity").should("not.exist");
+ eventsTable().findByText("No calls found").should("be.visible");
+
+ cy.log("Clearing the API key filter restores the call");
+ selectApiKeyFilter("All API keys");
+ eventsTable().findByText(SEEDED_KEY_NAME).should("be.visible");
+
+ cy.log("Widening the date range still includes the just-seeded call");
+ cy.findByTestId("conversation-filters-date-select").click();
+ H.popover().findByText("Last 7 days").click();
+ eventsTable().findByText(SEEDED_KEY_NAME).should("be.visible");
+ });
+});
diff --git a/enterprise/backend/src/metabase_enterprise/api_keys/db.clj b/enterprise/backend/src/metabase_enterprise/api_keys/db.clj
new file mode 100644
index 00000000000..f09fba54da5
--- /dev/null
+++ b/enterprise/backend/src/metabase_enterprise/api_keys/db.clj
@@ -0,0 +1,15 @@
+(ns metabase-enterprise.api-keys.db
+ "Application database queries for the enterprise api-keys module. Every function here is a direct Toucan 2 call with
+ no additional logic, so the rest of the module never talks to `toucan2.core` itself."
+ (:require
+ [toucan2.core :as t2]))
+
+(defn insert-usage-logs!
+ "Insert the ApiKeyUsageLog `rows` as one batch."
+ [rows]
+ (t2/insert! :model/ApiKeyUsageLog rows))
+
+(defn delete-usage-logs-occurred-before!
+ "Delete the ApiKeyUsageLogs whose `occurred_at` is before `cutoff`, returning the number deleted."
+ [cutoff]
+ (t2/delete! :model/ApiKeyUsageLog {:where [:< :occurred_at cutoff]}))
diff --git a/enterprise/backend/src/metabase_enterprise/api_keys/init.clj b/enterprise/backend/src/metabase_enterprise/api_keys/init.clj
new file mode 100644
index 00000000000..52e0a1d5445
--- /dev/null
+++ b/enterprise/backend/src/metabase_enterprise/api_keys/init.clj
@@ -0,0 +1,13 @@
+(ns metabase-enterprise.api-keys.init
+ "Startup wiring for the enterprise API keys module — loads the scheduled API key usage trimmer and
+ the usage/last_used_at flush loop so their lifecycle methods run on boot (on every EE instance,
+ matching where API key usage is collected).
+
+ `metabase-enterprise.api-keys.usage` is a `defenterprise` implementation namespace, which `require`s
+ lazily on the *first call* to `metabase.api-keys.usage/record-api-key-usage!` — too late for its
+ `task/init!` (trimmer) and `startup/def-startup-logic!`/`def-shutdown-logic!` (flush loop)
+ registrations, which are each walked once at boot/shutdown. Requiring it here forces it to load up
+ front instead."
+ (:require
+ [metabase-enterprise.api-keys.task.api-key-usage-trimmer]
+ [metabase-enterprise.api-keys.usage]))
diff --git a/enterprise/backend/src/metabase_enterprise/api_keys/task/api_key_usage_trimmer.clj b/enterprise/backend/src/metabase_enterprise/api_keys/task/api_key_usage_trimmer.clj
new file mode 100644
index 00000000000..bfb19e120a0
--- /dev/null
+++ b/enterprise/backend/src/metabase_enterprise/api_keys/task/api_key_usage_trimmer.clj
@@ -0,0 +1,53 @@
+(ns metabase-enterprise.api-keys.task.api-key-usage-trimmer
+ "Scheduled task to delete `api_key_usage_log` rows older than the configured
+ `ai-usage-max-retention-days`. Mirrors the Metabot `ai-usage-trimmer`, the MCP usage trimmer, and
+ the Agent API usage trimmer: API key usage is collected on every EE instance, so its retention
+ runs on every EE instance too — deliberately *not* audit-app-gated (which would let data grow
+ unbounded on instances that collect but can't view it)."
+ (:require
+ [clojurewerkz.quartzite.jobs :as jobs]
+ [clojurewerkz.quartzite.schedule.cron :as cron]
+ [clojurewerkz.quartzite.triggers :as triggers]
+ [java-time.api :as t]
+ [metabase-enterprise.api-keys.db :as api-keys.db]
+ [metabase.metabot.settings :as metabot.settings]
+ [metabase.task.core :as task]
+ [metabase.util.log :as log])
+ (:import
+ (org.quartz DisallowConcurrentExecution)))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private trimmer-job-key (jobs/key "metabase.task.api-keys.usage-trimmer.job"))
+(def ^:private trimmer-trigger-key (triggers/key "metabase.task.api-keys.usage-trimmer.trigger"))
+
+(defn- trim-old-api-key-usage-data!
+ []
+ (let [retention-days (metabot.settings/ai-usage-max-retention-days)]
+ (if (nil? retention-days)
+ (log/info "Skipping API key usage log cleanup; ai-usage-max-retention-days is 0 (infinite retention).")
+ (let [cutoff (t/minus (t/offset-date-time) (t/days (long retention-days)))]
+ (log/infof "Trimming API key usage log rows older than %d days." (long retention-days))
+ (let [rows (api-keys.db/delete-usage-logs-occurred-before! cutoff)]
+ (log/infof "API key usage log cleanup complete. Deleted %d rows." (or rows 0)))))))
+
+(task/defjob ^{DisallowConcurrentExecution true
+ :doc "Delete old API key usage log rows"}
+ ApiKeyUsageTrimmer [_ctx]
+ (trim-old-api-key-usage-data!))
+
+(defmethod task/init! ::ApiKeyUsageTrimmer
+ [_]
+ (let [job (jobs/build
+ (jobs/of-type ApiKeyUsageTrimmer)
+ (jobs/with-identity trimmer-job-key))
+ trigger (triggers/build
+ (triggers/with-identity trimmer-trigger-key)
+ (triggers/start-now)
+ (triggers/with-schedule
+ ;; Quartz 6-field cron (sec min hour day-of-month month day-of-week): daily at
+ ;; 23:29:41. The offset from the MCP (23:19:41) and Agent API (23:24:41) trimmers
+ ;; just staggers the independent jobs (different tables) so they don't fire at the
+ ;; same instant — it's not a dependency; overlapping runs would be harmless.
+ (cron/cron-schedule "41 29 23 * * ?")))]
+ (task/schedule-task! job trigger)))
diff --git a/enterprise/backend/src/metabase_enterprise/api_keys/usage.clj b/enterprise/backend/src/metabase_enterprise/api_keys/usage.clj
new file mode 100644
index 00000000000..f684266b4ed
--- /dev/null
+++ b/enterprise/backend/src/metabase_enterprise/api_keys/usage.clj
@@ -0,0 +1,300 @@
+(ns metabase-enterprise.api-keys.usage
+ "Enterprise implementation of API-key usage logging.
+
+ Writes one lean `api_key_usage_log` row per API-key-authenticated request and stamps
+ `api_key.last_used_at` for liveness. Collection runs on every EE instance (`:feature :none`),
+ mirroring `ai_usage_log`; the `ip_address` and `user_agent` columns are populated only when
+ `analytics-pii-retention-enabled` is on (itself `:audit-app`-gated). The table has no free-text
+ error column to gate — see `metabase.api-keys.usage` for why.
+
+ Both writes coalesce in memory and flush on a fixed interval via a scheduled task, not Grouper: a
+ Grouper queue falls back to a *blocking* put once full, which would stall the request thread behind
+ a slow DB write. The usage-log write bounds a pending vector and drops (logged) rather than blocks
+ once full; the last_used_at write coalesces to one pending entry per key, so it never needs a
+ capacity bound at all — see the two sections below for each.
+
+ Every write is best-effort: a failure is logged and swallowed so logging never fails the API
+ request and adds negligible latency. The two writes are independent of each other's success or
+ failure, even though callers only see a single [[record-api-key-usage!]] entry point."
+ (:require
+ [java-time.api :as t]
+ [metabase-enterprise.api-keys.db :as ee.api-keys.db]
+ [metabase.analytics.core :as analytics]
+ [metabase.analytics.sdk :as analytics.sdk]
+ [metabase.api-keys.core :as api-keys]
+ [metabase.api-keys.usage :as api-keys.usage]
+ [metabase.premium-features.core :refer [defenterprise]]
+ [metabase.request.core :as request]
+ [metabase.startup.core :as startup]
+ [metabase.util :as u]
+ [metabase.util.log :as log])
+ (:import
+ (java.util.concurrent Executors ScheduledExecutorService ThreadFactory TimeUnit)))
+
+(set! *warn-on-reflection* true)
+
+(def ^:private route-template-max-length
+ "Cap on the stored route_template length, matching the `api_key_usage_log.route_template` column width."
+ 255)
+
+(def ^:private unmatched-route-template
+ "Recorded in `route_template` when a request authenticated with an API key reached routing but
+ matched no endpoint (a real 404) — an absent template here is a real, valid event (someone probing
+ for routes, a client hitting a typo'd URL), not something to discard. Distinguishable from a real
+ template at a glance: a matched template always starts with `/`."
+ "(unmatched)")
+
+(def ^:private no-route-template
+ "Recorded in `route_template` when a request authenticated with an API key reached a handler that
+ isn't `defendpoint`-based (health checks, docs, a premium-feature 402 raised before routing) — nil
+ here, unlike [[unmatched-route-template]], doesn't mean someone probed for a nonexistent route."
+ "(no-template)")
+
+(def ^:private http-method-max-length
+ "Cap on the stored http_method length, matching the `api_key_usage_log.http_method` column width."
+ 10)
+
+(def ^:private ip-address-max-length
+ "Cap on the stored ip_address length, matching the `api_key_usage_log.ip_address` column width. Long
+ enough for IPv6; a forwarded-for header longer than that is truncated rather than failing the insert."
+ 45)
+
+(def ^:private embedding-client-max-length
+ "Cap on the stored embedding_client length, matching the `api_key_usage_log.embedding_client` column
+ width. Caller-supplied and unvalidated, unlike client_name — truncate rather than fail the insert."
+ 255)
+
+(def ^:private embedding-hostname-max-length
+ "Cap on the stored embedding_hostname length, matching the `api_key_usage_log.embedding_hostname`
+ column width. `extract-hostname` already truncates to this width; kept here so this row survives a
+ future change to that shared helper."
+ 512)
+
+;;; ------------------------------------------------- usage log ----------------------------------------------------
+
+(def ^:private usage-log-batch-capacity
+ "How many rows the pending usage-log queue holds before a new row is dropped rather than queued."
+ 500)
+
+(def ^:private flush-interval-seconds
+ "How often pending usage-log rows and last_used_at stamps flush to the database."
+ 10)
+
+(def ^:private not-null-columns
+ "The `api_key_usage_log` columns declared NOT NULL that this namespace can't always fill in from the
+ request alone. Rows are inserted in batches, so a row missing one of these would fail every row
+ batched with it, not just itself — an incomplete row is dropped before it is queued instead.
+ `route_template` isn't here: an unmatched route is a real event, recorded as
+ [[unmatched-route-template]] rather than discarded — see [[record-api-key-usage!]]."
+ [:api_key_id :http_method :status :duration_ms :client_name])
+
+(defonce ^:private pending-usage-logs (atom []))
+
+;; Counts drops between flushes rather than logging each one — a burst past the cap can drop
+;; hundreds of rows a second, and one warning per row would itself flood the log. See
+;; [[flush-usage-logs!]], which logs the total once and resets this.
+(defonce ^:private dropped-usage-log-count (atom 0))
+
+(defn- offer-usage-log!
+ "Appends `row` to the pending batch, unless it's already at [[usage-log-batch-capacity]] — a full
+ queue drops the row rather than blocking the request thread waiting for room. Uses `swap-vals!`
+ rather than a `volatile!` set from inside the `swap!` function: under CAS contention `swap!` can
+ invoke that function more than once, so an early attempt that sees the queue full and flags a drop
+ can still lose the race to a retry that finds room and conjes the row — counting a drop for a row
+ that was actually queued. Comparing the before/after values instead only counts a drop for the
+ transition that actually won."
+ [row]
+ (let [[old new] (swap-vals! pending-usage-logs
+ (fn [rows]
+ (if (>= (count rows) usage-log-batch-capacity)
+ rows
+ (conj rows row))))]
+ (when (identical? old new)
+ (swap! dropped-usage-log-count inc))))
+
+(defn- flush-usage-logs!
+ "Scheduled-task handler: atomically take the current pending rows and insert them as one batch.
+ Also takes and logs, once, the row count [[offer-usage-log!]] dropped since the last flush — see
+ [[dropped-usage-log-count]]."
+ []
+ (let [[rows] (reset-vals! pending-usage-logs [])
+ [dropped] (reset-vals! dropped-usage-log-count 0)]
+ (when (pos? dropped)
+ (log/warnf "Dropped %d API key usage log rows; the pending queue was full" dropped))
+ (when (seq rows)
+ (log/debugf "Inserting %d api_key_usage_log rows" (count rows))
+ (try
+ (ee.api-keys.db/insert-usage-logs! rows)
+ (catch Throwable e
+ (log/warn e "Failed to insert API key usage log rows"))))))
+
+;;; ---------------------------------------------- last_used_at ----------------------------------------------------
+
+;; A coalescing map, not a Grouper queue of events: a Grouper queue keeps every event until it flushes, so a hot
+;; key piles up hundreds of entries between flushes only to have all but the newest discarded at flush time. Here,
+;; each request updates its key's entry *in place* — a busy key costs one map entry, not one entry per request — and
+;; a scheduled task flushes the current contents on a fixed interval. `reset-vals!` atomically swaps in a fresh
+;; empty map and returns the one it replaced, so a request arriving mid-flush lands in the new map and is picked up
+;; next interval, never lost and never blocking the flush.
+
+;; api-key-id -> the latest `occurred-at` seen for it since the last flush.
+(defonce ^:private pending-last-used-at (atom {}))
+
+(defn- stamp-last-used-at! [api-key-id timestamp]
+ (swap! pending-last-used-at update api-key-id
+ (fn [existing] (if existing (t/max existing timestamp) timestamp))))
+
+(defn- flush-last-used-at!
+ "Scheduled-task handler: atomically take the current pending map and issue one bulk UPDATE for it.
+ Keys skipped because a concurrent writer held the row go back into the pending map for the next
+ flush, merged against whatever arrived for them in the meantime (the newer of the two wins) rather
+ than overwriting it."
+ []
+ (let [[batch] (reset-vals! pending-last-used-at {})]
+ (when (seq batch)
+ (log/debugf "Updating last_used_at for %d API keys" (count batch))
+ (try
+ (let [skipped (api-keys/update-api-keys-last-used-at! batch)]
+ (when (seq skipped)
+ (log/debugf "Retrying last_used_at for %d busy API keys next flush" (count skipped))
+ (swap! pending-last-used-at #(merge-with t/max % skipped))))
+ (catch Throwable e
+ (log/warn e "Failed to update API key last_used_at"))))))
+
+;;; -------------------------------------------- flush scheduling ---------------------------------------------------
+
+;; A JVM-local scheduled executor, not Quartz: pending-usage-logs and pending-last-used-at are per-JVM
+;; atoms, but our Quartz is clustered (JDBC job store), so a recurring trigger only ever fires on one
+;; node. A node that never wins trigger acquisition would never flush its own in-memory state — its
+;; usage-log queue would fill and drop every row, and its last_used_at stamps would never reach the
+;; DB. Each node instead runs its own single-threaded executor for its own pending state, mirroring
+;; `metabase.mq.publish-buffer`.
+
+(defn- safe-flush!
+ "Runs both flush functions, swallowing any throwable. `scheduleAtFixedRate` silently stops
+ rescheduling a task that throws an uncaught exception, which would freeze the flusher for the rest
+ of the JVM's life; each flush function already catches its own errors, but this is a second line of
+ defense so a future change to either can't silently kill the flush loop."
+ []
+ (try
+ (flush-usage-logs!)
+ (flush-last-used-at!)
+ (catch Throwable e
+ (log/error e "Unexpected error in API key usage flush; flusher continues"))))
+
+(defonce ^:private flush-executor (atom nil))
+
+(defn- start-flush!
+ "Starts a daemon thread that flushes pending usage-log rows and last_used_at stamps every
+ [[flush-interval-seconds]]. Idempotent. Returns `true` if THIS call created the executor, `false`
+ if one was already running."
+ []
+ (let [exec (Executors/newSingleThreadScheduledExecutor
+ (reify ThreadFactory
+ (newThread [_ r]
+ (doto (Thread. r "api-key-usage-flush")
+ (.setDaemon true)))))]
+ (if (compare-and-set! flush-executor nil exec)
+ (do (.scheduleAtFixedRate exec ^Runnable safe-flush! flush-interval-seconds flush-interval-seconds TimeUnit/SECONDS)
+ true)
+ (do (.shutdown exec) false))))
+
+(defn- stop-flush!
+ "Stops the flush thread, then force-flushes anything still pending so a graceful shutdown doesn't
+ lose the last interval's worth of rows/stamps."
+ []
+ (when-let [^ScheduledExecutorService exec (first (reset-vals! flush-executor nil))]
+ (.shutdownNow exec))
+ (safe-flush!))
+
+(defmethod startup/def-startup-logic! ::ApiKeyUsageFlush
+ [_]
+ (start-flush!))
+
+(defmethod startup/def-shutdown-logic! ::ApiKeyUsageFlush
+ [_]
+ (stop-flush!))
+
+;;; ------------------------------------------------- entry point ---------------------------------------------------
+
+(defn- request-user-agent [request] (get-in request [:headers "user-agent"]))
+(defn- request-embedding-client [request] (get-in request [:headers "x-metabase-client"]))
+(defn- request-embedding-hostname [request]
+ (analytics.sdk/extract-hostname (get-in request [:headers "x-metabase-embed-referrer"])))
+
+(defenterprise record-api-key-usage!
+ "EE: record one completed API-key-authenticated request. Queues one `api_key_usage_log` row and one
+ `last_used_at` event, both flushed on a scheduled interval, never synchronously on the request thread.
+
+ Takes the raw `request`/`response` and extracts everything itself, plus `extra-info` for the
+ handful of values only the caller can supply: `route-template` (read from the carrier the caller
+ installed before routing ran — see `metabase.api.macros/route-template-carrier-key`; nil for a
+ request that never reached a `defendpoint` handler, recorded as [[unmatched-route-template]] for a
+ real 404 or [[no-route-template]] otherwise (health checks, docs, a 402 raised before routing) —
+ rather than dropping the row, since neither case is an incomplete event), `duration-ms` (measured by the
+ caller around the whole request), and `occurred-at` (captured on the request thread rather than left
+ for the DB to fill in at INSERT time — the row lands via a scheduled flush, up to the flush interval
+ later, so a DB-computed default would record when the flush ran, not when the request happened).
+
+ `user_id` is the key's own synthetic service-account user (used for permission checks, not a real
+ person); `created_by_id` is the real human who created the key, read off the same auth query — see
+ `metabase.server.db/user-data-for-api-key-prefix-query`. Both non-PII.
+
+ `ip_address` and `user_agent` are PII — stored only when `analytics-pii-retention-enabled` is on.
+ `client_name` is classified from `user-agent` via [[metabase.api-keys.usage/detect-client]] and
+ always recorded — non-PII, mirrors `agent_api_call_log`'s `client_name`. `embedding_client` is the
+ raw `X-Metabase-Client` header, passed through unclassified and non-PII, supplementary to
+ `client_name`. `embedding_hostname` is the hostname parsed from the embed referrer header, non-PII,
+ always recorded — only meaningful alongside `embedding_client`. `route_template`, `http_method`,
+ `embedding_client`, and `embedding_hostname` are truncated to their column widths; a row missing a
+ NOT NULL value the caller can't have controlled (see [[not-null-columns]]) is dropped rather than
+ queued, so it can't sink the batch it would land in — the `last_used_at` event is queued regardless,
+ since `api-key-id` is always present on an API-key-authenticated request."
+ :feature :none
+ [request response {:keys [route-template duration-ms occurred-at]}]
+ (let [api-key-id (:api-key-id request)
+ user-agent (request-user-agent request)
+ occurred-at (or occurred-at (t/offset-date-time))]
+ (when api-key-id
+ (try
+ (stamp-last-used-at! api-key-id occurred-at)
+ (catch Throwable e
+ (log/warn e "Failed to record API key last_used_at"))))
+ (try
+ (let [;; `pii-fields-from` returns the gated PII columns only when retention is on (nil
+ ;; otherwise). Allowlist the two columns this row has, so a new field on the shared helper
+ ;; can't silently start persisting here without a deliberate change.
+ pii (some-> (analytics/pii-fields-from {:user-agent user-agent
+ :ip-address (request/ip-address request)})
+ (select-keys [:user_agent :ip_address])
+ (update :ip_address #(some-> % (u/truncate ip-address-max-length))))
+ row (merge {:api_key_id api-key-id
+ :user_id (:metabase-user-id request)
+ :created_by_id (:api-key-creator-id request)
+ :route_template (or (some-> route-template (u/truncate route-template-max-length))
+ (if (= 404 (:status response))
+ unmatched-route-template
+ no-route-template))
+ :http_method (some-> (:request-method request) name u/upper-case-en
+ (u/truncate http-method-max-length))
+ :status (:status response)
+ :duration_ms duration-ms
+ :occurred_at occurred-at
+ :client_name (api-keys.usage/detect-client user-agent)
+ :embedding_client (some-> (request-embedding-client request) (u/truncate embedding-client-max-length))
+ :embedding_hostname (some-> (request-embedding-hostname request) (u/truncate embedding-hostname-max-length))}
+ pii)]
+ (if-let [missing (not-empty (remove #(some? (get row %)) not-null-columns))]
+ (log/warnf "Not recording API key usage log row, missing %s" (pr-str missing))
+ (offer-usage-log! row)))
+ (catch Throwable e
+ (log/warn e "Failed to record API key usage")))))
+
+(defenterprise flush-pending-writes!
+ "EE: synchronously flush the pending usage-log and last_used_at batches instead of waiting for the
+ scheduled interval. Only meaningful for tests that need a just-recorded event to be immediately
+ queryable."
+ :feature :none
+ []
+ (flush-usage-logs!)
+ (flush-last-used-at!))
diff --git a/enterprise/backend/src/metabase_enterprise/audit_app/permissions.clj b/enterprise/backend/src/metabase_enterprise/audit_app/permissions.clj
index f551828f6a1..0761c7834a1 100644
--- a/enterprise/backend/src/metabase_enterprise/audit_app/permissions.clj
+++ b/enterprise/backend/src/metabase_enterprise/audit_app/permissions.clj
@@ -34,7 +34,8 @@
"v_metabot_messages"
"v_ai_usage_log"
"v_mcp_tool_calls"
- "v_agent_api_calls"})
+ "v_agent_api_calls"
+ "v_api_key_usage"})
(defenterprise check-audit-db-permissions
"Performs a number of permission checks to ensure that a query on the Audit database can be run.
diff --git a/enterprise/backend/src/metabase_enterprise/core/init.clj b/enterprise/backend/src/metabase_enterprise/core/init.clj
index 5f5f6c46683..92ecf9e0d37 100644
--- a/enterprise/backend/src/metabase_enterprise/core/init.clj
+++ b/enterprise/backend/src/metabase_enterprise/core/init.clj
@@ -9,6 +9,7 @@
[metabase-enterprise.action-v2.init]
[metabase-enterprise.advanced-config.init]
[metabase-enterprise.agent-api.init]
+ [metabase-enterprise.api-keys.init]
[metabase-enterprise.audit-app.init]
[metabase-enterprise.cache.init]
[metabase-enterprise.custom-viz-plugin.init]
diff --git a/enterprise/backend/src/metabase_enterprise/serialization/v2/models.clj b/enterprise/backend/src/metabase_enterprise/serialization/v2/models.clj
index c5c70beeaf2..60c4014f2db 100644
--- a/enterprise/backend/src/metabase_enterprise/serialization/v2/models.clj
+++ b/enterprise/backend/src/metabase_enterprise/serialization/v2/models.clj
@@ -72,6 +72,7 @@
"AnalysisFinding"
"AnalysisFindingError"
"ApiKey"
+ "ApiKeyUsageLog"
"ApplicationPermissionsRevision"
"AuditLog"
"AuthIdentity"
diff --git a/enterprise/backend/test/metabase_enterprise/api_keys/task/api_key_usage_trimmer_test.clj b/enterprise/backend/test/metabase_enterprise/api_keys/task/api_key_usage_trimmer_test.clj
new file mode 100644
index 00000000000..16b20327600
--- /dev/null
+++ b/enterprise/backend/test/metabase_enterprise/api_keys/task/api_key_usage_trimmer_test.clj
@@ -0,0 +1,46 @@
+(ns metabase-enterprise.api-keys.task.api-key-usage-trimmer-test
+ (:require
+ [clojure.test :refer :all]
+ [java-time.api :as t]
+ [metabase-enterprise.api-keys.task.api-key-usage-trimmer :as api-key-usage-trimmer]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [toucan2.core :as t2]))
+
+(use-fixtures :once (fixtures/initialize :db))
+
+(set! *warn-on-reflection* true)
+
+;; NOTE: these tests deliberately do NOT wrap in `mt/with-premium-features #{:audit-app}` — API key
+;; usage is collected on every EE instance, so its trimmer must run regardless of the audit-app feature.
+
+(defn- usage-log [occurred-at]
+ {:api_key_id 1234
+ :route_template "/api/usage-trimmer-test/:id"
+ :http_method "GET"
+ :status 200
+ :duration_ms 12
+ :client_name "curl"
+ :occurred_at occurred-at})
+
+(deftest trims-rows-older-than-custom-retention-test
+ (testing "with retention set to 30 days, usage rows older than 30 days are deleted"
+ (mt/with-temp
+ [:model/ApiKeyUsageLog {recent :id} (usage-log (t/offset-date-time))
+ :model/ApiKeyUsageLog {boundary :id} (usage-log (t/minus (t/offset-date-time) (t/days 31)))
+ :model/ApiKeyUsageLog {old :id} (usage-log (t/minus (t/offset-date-time) (t/days 200)))]
+ (mt/with-temp-env-var-value! [mb-ai-usage-max-retention-days 30]
+ (#'api-key-usage-trimmer/trim-old-api-key-usage-data!)
+ (is (= #{recent}
+ (t2/select-fn-set :id :model/ApiKeyUsageLog {:where [:in :id [recent boundary old]]}))
+ "usage rows older than the cutoff are deleted, recent kept")))))
+
+(deftest skips-deletion-when-retention-is-infinite-test
+ (testing "when retention is set to 0 (infinite), no rows are deleted"
+ (mt/with-temp
+ [:model/ApiKeyUsageLog {recent :id} (usage-log (t/offset-date-time))
+ :model/ApiKeyUsageLog {old :id} (usage-log (t/minus (t/offset-date-time) (t/years 5)))]
+ (mt/with-temp-env-var-value! [mb-ai-usage-max-retention-days 0]
+ (#'api-key-usage-trimmer/trim-old-api-key-usage-data!)
+ (is (= #{recent old}
+ (t2/select-fn-set :id :model/ApiKeyUsageLog {:where [:in :id [recent old]]})))))))
diff --git a/enterprise/backend/test/metabase_enterprise/api_keys/usage_instrumentation_test.clj b/enterprise/backend/test/metabase_enterprise/api_keys/usage_instrumentation_test.clj
new file mode 100644
index 00000000000..5acb6fc6972
--- /dev/null
+++ b/enterprise/backend/test/metabase_enterprise/api_keys/usage_instrumentation_test.clj
@@ -0,0 +1,132 @@
+(ns metabase-enterprise.api-keys.usage-instrumentation-test
+ "End-to-end tests for the API-key usage hook in `metabase.server.middleware.log/log-api-call`: real HTTP requests
+ through the real middleware and routing stack, asserting the rows that actually land in `api_key_usage_log`.
+
+ The pieces are unit-tested elsewhere (`metabase-enterprise.api-keys.usage-test` for the recorders,
+ `metabase.server.middleware.log-test` for the hook, `metabase.api.util.handlers-test` for route-template
+ reconstruction). What can only be checked here is that they are wired together — in particular that
+ `route_template` survives the trip from the routing tree back up to the log middleware, which sees only the
+ pre-routing request."
+ (:require
+ [clojure.test :refer [deftest is testing use-fixtures]]
+ [metabase-enterprise.api-keys.usage :as ee-usage]
+ [metabase.permissions.core :as perms]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.test.http-client :as client]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db :test-users :web-server))
+
+(defn- rows-for!
+ "Forces the pending usage-log rows to flush before reading — they coalesce in memory between
+ scheduled flushes, so a row written moments ago may not be on disk yet."
+ [api-key-id]
+ (#'ee-usage/flush-usage-logs!)
+ (t2/select :model/ApiKeyUsageLog :api_key_id api-key-id {:order-by [[:id :asc]]}))
+
+(defn- last-used-at!
+ "Forces the pending `last_used_at` stamps to flush before reading — they coalesce in memory between
+ scheduled flushes, so a stamp made moments ago may not be on disk yet."
+ [api-key-id]
+ (#'ee-usage/flush-last-used-at!)
+ (t2/select-one-fn :last_used_at :model/ApiKey :id api-key-id))
+
+(defn- api-key-headers [unmasked-key]
+ {:request-options {:headers {"x-api-key" unmasked-key, "user-agent" "metabase-cli/1.2.3"}}})
+
+(defn- do-with-api-key!
+ "Create a real API key over the API, run `f` with its unmasked key and id, then clean up the key and its usage rows.
+ Both the usage-log row and the `last_used_at` stamp coalesce in memory between scheduled flushes —
+ see [[rows-for!]] and [[last-used-at!]], which force a flush before reading."
+ [f]
+ (let [{unmasked-key :unmasked_key, api-key-id :id}
+ (mt/user-http-request :crowberto :post 200 "api-key"
+ {:group_id (:id (perms/all-users-group))
+ :name (str (random-uuid))})]
+ (try
+ (f unmasked-key api-key-id)
+ (finally
+ (t2/delete! :model/ApiKeyUsageLog :api_key_id api-key-id)
+ (t2/delete! :model/ApiKey :id api-key-id)))))
+
+(deftest api-key-request-is-recorded-test
+ (testing "an API-key-authenticated request to a defendpoint records one row, attributed to the key that made it"
+ (do-with-api-key!
+ (fn [unmasked-key api-key-id]
+ (client/client :get 200 "user/current" (api-key-headers unmasked-key))
+ (let [[row :as rows] (rows-for! api-key-id)]
+ (is (= 1 (count rows)))
+ (testing "the route template made it up from the routing tree — this is the whole point of the hook"
+ (is (= "/api/user/current" (:route_template row))))
+ (is (= api-key-id (:api_key_id row)))
+ (is (= (t2/select-one-fn :user_id :model/ApiKey :id api-key-id) (:user_id row)))
+ (is (= (mt/user->id :crowberto) (:created_by_id row))
+ "crowberto created the key over the API in do-with-api-key!")
+ (is (= "GET" (:http_method row)))
+ (is (= 200 (:status row)))
+ (is (int? (:duration_ms row)))
+ (is (= "metabase-cli" (:client_name row)))
+ (testing "embedding_client is absent — the common case, no X-Metabase-Client header sent"
+ (is (nil? (:embedding_client row)))))
+ (testing "and last_used_at is stamped"
+ (is (some? (last-used-at! api-key-id))))))))
+
+(deftest api-key-request-records-embedding-client-test
+ (testing "the X-Metabase-Client header, when present, is recorded alongside client_name"
+ (do-with-api-key!
+ (fn [unmasked-key api-key-id]
+ (client/client :get 200 "user/current"
+ (update (api-key-headers unmasked-key) :request-options
+ update :headers assoc "x-metabase-client" "embedding-sdk-react"))
+ (let [[row] (rows-for! api-key-id)]
+ (is (= "embedding-sdk-react" (:embedding_client row)))
+ (testing "client_name stays the User-Agent classification — unaffected by the header"
+ (is (= "metabase-cli" (:client_name row)))))))))
+
+(deftest api-key-request-records-embedding-hostname-test
+ (testing "the embed referrer header, when present, is parsed into embedding_hostname alongside embedding_client"
+ (do-with-api-key!
+ (fn [unmasked-key api-key-id]
+ (client/client :get 200 "user/current"
+ (update (api-key-headers unmasked-key) :request-options
+ update :headers assoc
+ "x-metabase-client" "embedding-sdk-react"
+ "x-metabase-embed-referrer" "https://example.com/app"))
+ (let [[row] (rows-for! api-key-id)]
+ (is (= "embedding-sdk-react" (:embedding_client row)))
+ (is (= "example.com" (:embedding_hostname row))))))))
+
+(deftest api-key-request-records-the-template-not-the-uri-test
+ (testing "a route with a path param records the template, never the concrete id"
+ (do-with-api-key!
+ (fn [unmasked-key api-key-id]
+ ;; also the error path: `check-404` *throws*, so this response is built by `catch-api-exceptions` from the
+ ;; exception rather than by the endpoint. The route template still has to survive that.
+ (client/client :get 404 "card/99999999" (api-key-headers unmasked-key))
+ (let [[row] (rows-for! api-key-id)]
+ (is (= "/api/card/:id" (:route_template row)))
+ (is (= 404 (:status row))))))))
+
+(deftest session-authenticated-requests-are-not-recorded-test
+ (testing "requests authenticated any other way record nothing at all"
+ (do-with-api-key!
+ (fn [_unmasked-key api-key-id]
+ (let [rows-before (t2/count :model/ApiKeyUsageLog)]
+ (mt/user-http-request :crowberto :get 200 "user/current")
+ (is (= rows-before (t2/count :model/ApiKeyUsageLog)))
+ (is (empty? (rows-for! api-key-id))))))))
+
+(deftest unmatched-route-is-recorded-test
+ (testing "a request that matches no endpoint is still a real event — recorded with the unmatched sentinel,
+ not dropped"
+ (do-with-api-key!
+ (fn [unmasked-key api-key-id]
+ (client/client :get 404 "user/current/not-a-real-route" (api-key-headers unmasked-key))
+ (let [[row] (rows-for! api-key-id)]
+ (is (= "(unmatched)" (:route_template row)))
+ (is (= 404 (:status row))))
+ (testing "and the key is still marked as used — the request did authenticate"
+ (is (some? (last-used-at! api-key-id))))))))
diff --git a/enterprise/backend/test/metabase_enterprise/api_keys/usage_test.clj b/enterprise/backend/test/metabase_enterprise/api_keys/usage_test.clj
new file mode 100644
index 00000000000..173cd286dc6
--- /dev/null
+++ b/enterprise/backend/test/metabase_enterprise/api_keys/usage_test.clj
@@ -0,0 +1,499 @@
+(ns metabase-enterprise.api-keys.usage-test
+ "Tests for [[metabase.api-keys.usage/record-api-key-usage!]] — one lean `api_key_usage_log` row per
+ API-key-authenticated request, plus the `api_key.last_used_at` stamp. Exercises the `defenterprise`
+ dispatch via the OSS entry point in `metabase.api-keys.usage`. Collection runs on every EE instance
+ (`:feature :none`); PII is gated by `analytics-pii-retention-enabled` (itself `:audit-app`-gated).
+ Both writes coalesce in memory between scheduled flushes — [[record!]] forces the usage-log flush on
+ every call; `last_used_at` tests call the private `flush-last-used-at!` explicitly, since some of
+ them specifically check the pre-flush state. `synchronous-batch-updates` no longer applies to either
+ write — it only ever affected Grouper, which neither path uses anymore."
+ (:require
+ [clojure.test :refer [deftest is testing use-fixtures]]
+ [java-time.api :as t]
+ [metabase-enterprise.api-keys.usage :as ee-usage]
+ [metabase.api-keys.core :as api-keys]
+ [metabase.api-keys.usage :as usage]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [metabase.util :as u]
+ [toucan2.core :as t2]))
+
+(set! *warn-on-reflection* true)
+
+(use-fixtures :once (fixtures/initialize :db :test-users))
+
+(defn- unique-route
+ "A route template unique to one test, so rows can be found and cleaned up without colliding with
+ anything else in the table."
+ []
+ (str "/api/usage-test/" (mt/random-name) "/:id"))
+
+(defn- row-for [route]
+ (t2/select-one :model/ApiKeyUsageLog :route_template route))
+
+(defn- last-used-at [api-key-id]
+ (t2/select-one-fn :last_used_at :model/ApiKey :id api-key-id))
+
+(defn- request-info
+ "A complete [[record!]] input map, overridable per test."
+ [route & {:as overrides}]
+ (merge {:api-key-id 1234
+ :user-id (mt/user->id :rasta)
+ :creator-id (mt/user->id :crowberto)
+ :route-template route
+ :http-method "GET"
+ :status 200
+ :duration-ms 12
+ :user-agent "curl/8.4.0"
+ :ip-address "203.0.113.7"}
+ overrides))
+
+(defn- record!
+ "Translates a flat [[request-info]] map into the real `(request response extra-info)` shape the
+ recorder now takes, invokes it, then forces the usage-log row to flush — it coalesces in memory
+ between scheduled flushes, so a row written moments ago may not be on disk yet. (`last_used_at` is
+ not flushed here — tests that need it call the private `flush-last-used-at!` explicitly, since some
+ of them specifically check the pre-flush state.)"
+ [{:keys [api-key-id user-id creator-id route-template http-method status duration-ms occurred-at
+ user-agent ip-address embedding-client embedding-hostname]}]
+ (usage/record-api-key-usage!
+ {:api-key-id api-key-id
+ :metabase-user-id user-id
+ :api-key-creator-id creator-id
+ :request-method (some-> http-method u/lower-case-en keyword)
+ :headers (cond-> {}
+ user-agent (assoc "user-agent" user-agent)
+ ip-address (assoc "x-forwarded-for" ip-address)
+ embedding-client (assoc "x-metabase-client" embedding-client)
+ embedding-hostname (assoc "x-metabase-embed-referrer" (str "https://" embedding-hostname)))}
+ {:status status}
+ {:route-template route-template
+ :duration-ms duration-ms
+ :occurred-at occurred-at})
+ (#'ee-usage/flush-usage-logs!))
+
+;;; ------------------------------------------- usage log row --------------------------------------------
+
+(deftest record-api-key-usage!-writes-row-test
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true
+ analytics-pii-retention-enabled true]
+ (let [route (unique-route)]
+ (try
+ (record! (request-info route
+ :http-method "POST"
+ :status 201))
+ (let [row (row-for route)]
+ (testing "non-PII columns"
+ (is (= 1234 (:api_key_id row)))
+ (is (= (mt/user->id :rasta) (:user_id row)))
+ (is (= (mt/user->id :crowberto) (:created_by_id row)))
+ (is (= "POST" (:http_method row)))
+ (is (= 201 (:status row)))
+ (is (= 12 (:duration_ms row)))
+ (is (some? (:occurred_at row)))
+ (is (= "curl" (:client_name row))))
+ (testing "PII columns populated when retention is on"
+ (is (= "curl/8.4.0" (:user_agent row)))
+ (is (= "203.0.113.7" (:ip_address row)))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route)))))))
+
+(deftest record-api-key-usage!-occurred-at-is-caller-supplied-test
+ (testing "occurred_at reflects the caller's timestamp, not whenever the batch happens to flush"
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true]
+ (let [route (unique-route)
+ ;; truncated to microseconds to match real DB storage precision; H2 alone preserves nanoseconds.
+ occurred-at (-> (t/instant) (t/minus (t/hours 3)) (t/truncate-to :micros)
+ (t/offset-date-time (t/zone-offset 0)))]
+ (try
+ (record! (request-info route :occurred-at occurred-at))
+ (is (= occurred-at (:occurred_at (row-for route))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))
+
+(deftest record-api-key-usage!-pii-gate-test
+ (testing "ip_address / user_agent are stored only when retention is on"
+ (mt/with-premium-features #{:audit-app}
+ (testing "retention on: PII columns populated"
+ (mt/with-temporary-setting-values [synchronous-batch-updates true
+ analytics-pii-retention-enabled true]
+ (let [route (unique-route)]
+ (try
+ (record! (request-info route))
+ (let [row (row-for route)]
+ (is (= "curl/8.4.0" (:user_agent row)))
+ (is (= "203.0.113.7" (:ip_address row))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))
+ (testing "retention off: the row is still written, PII columns stay null"
+ (mt/with-temporary-setting-values [synchronous-batch-updates true
+ analytics-pii-retention-enabled false]
+ (let [route (unique-route)]
+ (try
+ (record! (request-info route))
+ (let [row (row-for route)]
+ (is (some? row))
+ (is (= 200 (:status row)))
+ (is (nil? (:user_agent row)))
+ (is (nil? (:ip_address row))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route)))))))))
+
+(deftest record-api-key-usage!-client-name-is-never-gated-test
+ (testing "client_name is classified from user-agent and recorded even when PII retention is off"
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true
+ analytics-pii-retention-enabled false]
+ (let [route (unique-route)]
+ (try
+ (record! (request-info route :user-agent "metabase-cli/1.2.3"))
+ (let [row (row-for route)]
+ (is (= "metabase-cli" (:client_name row)))
+ (testing "but the raw user_agent stays gated"
+ (is (nil? (:user_agent row)))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))
+
+(deftest record-api-key-usage!-embedding-client-test
+ (testing "embedding_client carries the raw X-Metabase-Client header, never gated, unlike client_name it's not classified"
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true
+ analytics-pii-retention-enabled false]
+ (let [route (unique-route)]
+ (try
+ (record! (request-info route :embedding-client "embedding-sdk-react"))
+ (is (= "embedding-sdk-react" (:embedding_client (row-for route))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route)))))))
+ (testing "absent when not passed — the common case for API-key traffic"
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true]
+ (let [route (unique-route)]
+ (try
+ (record! (request-info route))
+ (is (nil? (:embedding_client (row-for route))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))
+
+(deftest record-api-key-usage!-truncates-embedding-client-test
+ (testing "an over-long embedding_client is truncated to the column width so the row still records"
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true]
+ (let [route (unique-route)
+ long-value (apply str (repeat 300 \x))]
+ (try
+ (record! (request-info route :embedding-client long-value))
+ (is (= 255 (count (:embedding_client (row-for route)))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))
+
+(deftest record-api-key-usage!-embedding-hostname-test
+ (testing "embedding_hostname carries the parsed hostname, never gated"
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true
+ analytics-pii-retention-enabled false]
+ (let [route (unique-route)]
+ (try
+ (record! (request-info route :embedding-hostname "example.com"))
+ (is (= "example.com" (:embedding_hostname (row-for route))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route)))))))
+ (testing "absent when not passed"
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true]
+ (let [route (unique-route)]
+ (try
+ (record! (request-info route))
+ (is (nil? (:embedding_hostname (row-for route))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))
+
+(deftest record-api-key-usage!-truncates-embedding-hostname-test
+ (testing "an over-long embedding_hostname is truncated to the column width so the row still records"
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true]
+ (let [route (unique-route)
+ long-value (apply str (repeat 600 \x))]
+ (try
+ (record! (request-info route :embedding-hostname long-value))
+ (is (= 512 (count (:embedding_hostname (row-for route)))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))
+
+(deftest record-api-key-usage!-unrecognized-user-agent-is-other-test
+ (testing "an unrecognized or absent User-Agent classifies as \"other\""
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true]
+ (let [route (unique-route)]
+ (try
+ (record! (request-info route :user-agent nil))
+ (is (= "other" (:client_name (row-for route))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))
+
+(deftest record-api-key-usage!-truncates-route-template-test
+ (testing "an over-long route_template is truncated to the column width so the row still records"
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true]
+ (let [route (apply str (unique-route) (repeat 300 \x))]
+ (try
+ (record! (request-info route))
+ (is (= 255 (count (:route_template (row-for (subs route 0 255))))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template (subs route 0 255)))))))))
+
+(deftest record-api-key-usage!-unmatched-route-is-recorded-test
+ (testing "a nil route-template on a 404 is recorded with the unmatched sentinel, not dropped"
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true]
+ ;; a dedicated api-key-id, since the stored route_template is the sentinel rather than
+ ;; `route` — this test can't find its row by route like the others do
+ (let [api-key-id 424242]
+ (try
+ (record! (request-info (unique-route) :api-key-id api-key-id :route-template nil :status 404))
+ (is (= "(unmatched)"
+ (:route_template (t2/select-one :model/ApiKeyUsageLog :api_key_id api-key-id))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :api_key_id api-key-id))))))))
+
+(deftest record-api-key-usage!-non-404-nil-route-template-is-recorded-test
+ (testing "a nil route-template on anything other than a 404 (health checks, docs, a 402 raised
+ before routing) is recorded with a different sentinel — it isn't someone probing for a
+ nonexistent route, so labeling it the same way would be misleading"
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true]
+ (let [api-key-id 434343]
+ (try
+ (record! (request-info (unique-route) :api-key-id api-key-id :route-template nil :status 200))
+ (is (= "(no-template)"
+ (:route_template (t2/select-one :model/ApiKeyUsageLog :api_key_id api-key-id))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :api_key_id api-key-id))))))))
+
+(deftest record-api-key-usage!-drops-incomplete-log-row-test
+ (testing "a row missing a NOT NULL value is dropped rather than queued, so it can't sink its batch"
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true]
+ (let [route (unique-route)]
+ (try
+ (record! (request-info route :api-key-id nil))
+ (is (nil? (row-for route)))
+ (testing "a complete row still records afterwards"
+ (record! (request-info route))
+ (is (some? (row-for route))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))
+
+(deftest record-api-key-usage!-collection-runs-without-audit-app-test
+ (testing "collection happens on any EE instance (:feature :none), but PII stays null without :audit-app"
+ (mt/with-premium-features #{}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true]
+ (let [route (unique-route)]
+ (try
+ (record! (request-info route))
+ (let [row (row-for route)]
+ (testing "non-PII row is written"
+ (is (some? row))
+ (is (= (mt/user->id :rasta) (:user_id row))))
+ (testing "PII is null because retention can't be enabled without :audit-app"
+ (is (nil? (:user_agent row)))
+ (is (nil? (:ip_address row)))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))
+
+(deftest record-api-key-usage!-log-row-is-best-effort-test
+ (testing "a failed usage-log insert is swallowed and never propagates to the caller"
+ (mt/with-premium-features #{:audit-app}
+ (mt/with-temporary-setting-values [synchronous-batch-updates true]
+ (mt/with-dynamic-fn-redefs [t2/insert! (fn [& _] (throw (ex-info "boom" {})))]
+ (is (nil? (record! (request-info (unique-route))))))))))
+
+(deftest offer-usage-log!-drops-rows-once-full-test
+ (testing "a full pending queue drops a new row rather than blocking the request thread for room"
+ (let [pending (deref #'ee-usage/pending-usage-logs)
+ original @pending]
+ (try
+ (reset! pending (vec (repeat 500 {:dummy true})))
+ (#'ee-usage/offer-usage-log! {:dummy true})
+ (is (= 500 (count @pending)) "the queue was already at capacity, so the new row was dropped")
+ (finally (reset! pending original))))))
+
+(deftest offer-usage-log!-counts-drops-for-flush-to-log-once-test
+ (testing "drops accumulate in a counter that flush-usage-logs! takes and resets, rather than each drop logging on its own"
+ (let [pending (deref #'ee-usage/pending-usage-logs)
+ dropped (deref #'ee-usage/dropped-usage-log-count)
+ original-pending @pending
+ original-dropped @dropped]
+ (try
+ (reset! pending (vec (repeat 500 {:dummy true})))
+ (reset! dropped 0)
+ (#'ee-usage/offer-usage-log! {:dummy true})
+ (#'ee-usage/offer-usage-log! {:dummy true})
+ (is (= 2 @dropped) "two dropped rows are counted, not logged individually")
+ (reset! pending [])
+ (mt/with-log-messages-for-level [messages [metabase-enterprise.api-keys.usage :warn]]
+ (#'ee-usage/flush-usage-logs!)
+ (is (=? [{:level :warn, :message #"^Dropped 2 API key usage log rows.*"}]
+ (messages))
+ "the two drops are logged once, as a single total, not once per drop"))
+ (is (= 0 @dropped) "flush takes and resets the counter after logging the total once")
+ (finally
+ (reset! pending original-pending)
+ (reset! dropped original-dropped))))))
+
+;;; ------------------------------------------ last_used_at --------------------------------------------
+
+(deftest record-api-key-usage!-stamps-last-used-at-test
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/ApiKey {api-key-id :id} {::api-keys/unhashed-key "mb_1234567890"
+ :name (mt/random-name)
+ :user_id (mt/user->id :crowberto)
+ :creator_id (mt/user->id :crowberto)
+ :updated_by_id (mt/user->id :crowberto)}]
+ (let [updated-at-before (t2/select-one-fn :updated_at :model/ApiKey :id api-key-id)
+ route (unique-route)]
+ (try
+ (is (nil? (last-used-at api-key-id)))
+ (record! (request-info route :api-key-id api-key-id))
+ (testing "not written until the next flush — coalesced in memory, not a synchronous write"
+ (is (nil? (last-used-at api-key-id))))
+ (#'ee-usage/flush-last-used-at!)
+ (is (some? (last-used-at api-key-id)))
+ (testing "the stamp bypasses the model hooks, so updated_at never moves"
+ (is (= updated-at-before
+ (t2/select-one-fn :updated_at :model/ApiKey :id api-key-id))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route)))))))
+
+(deftest record-api-key-usage!-coalesces-last-used-at-before-flush-test
+ (testing "multiple events for the same key before a flush collapse to the max timestamp, one UPDATE"
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/ApiKey {api-key-id :id} {::api-keys/unhashed-key "mb_3333333333"
+ :name (mt/random-name)
+ :user_id (mt/user->id :crowberto)
+ :creator_id (mt/user->id :crowberto)
+ :updated_by_id (mt/user->id :crowberto)}]
+ ;; truncated to microseconds to match real DB storage precision; H2 alone preserves nanoseconds.
+ (let [now #(-> (t/instant) (t/truncate-to :micros) (t/offset-date-time (t/zone-offset 0)))
+ earlier (t/minus (now) (t/minutes 5))
+ later (now)
+ route (unique-route)]
+ (try
+ ;; out of order on purpose — the later timestamp must win regardless of arrival order
+ (record! (request-info route :api-key-id api-key-id :occurred-at later))
+ (record! (request-info route :api-key-id api-key-id :occurred-at earlier))
+ (#'ee-usage/flush-last-used-at!)
+ (is (= later (last-used-at api-key-id)))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))
+
+(deftest record-api-key-usage!-last-used-at-independent-per-key-test
+ (testing "one key's event does not affect another key's last_used_at"
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/ApiKey {key-1 :id} {::api-keys/unhashed-key "mb_1111111111"
+ :name (mt/random-name)
+ :user_id (mt/user->id :crowberto)
+ :creator_id (mt/user->id :crowberto)
+ :updated_by_id (mt/user->id :crowberto)}
+ :model/ApiKey {key-2 :id} {::api-keys/unhashed-key "mb_2222222222"
+ :name (mt/random-name)
+ :user_id (mt/user->id :crowberto)
+ :creator_id (mt/user->id :crowberto)
+ :updated_by_id (mt/user->id :crowberto)}]
+ (let [route (unique-route)]
+ (try
+ (record! (request-info route :api-key-id key-1))
+ (#'ee-usage/flush-last-used-at!)
+ (is (some? (last-used-at key-1)))
+ (is (nil? (last-used-at key-2)))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))
+
+(deftest record-api-key-usage!-last-used-at-is-best-effort-test
+ (testing "a nil id skips the write entirely"
+ (mt/with-premium-features #{}
+ (is (nil? (record! (request-info (unique-route) :api-key-id nil))))))
+ (testing "a failed flush is swallowed rather than thrown"
+ (mt/with-premium-features #{}
+ (let [route (unique-route)]
+ (try
+ (record! (request-info route :api-key-id Integer/MAX_VALUE))
+ (mt/with-dynamic-fn-redefs [t2/query (fn [& _] (throw (ex-info "boom" {})))]
+ (is (nil? (#'ee-usage/flush-last-used-at!))))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route)))))))
+
+(deftest flush-last-used-at!-requeues-skipped-keys-test
+ (testing "a key the DB layer skips (e.g. a busy row) goes back into the pending map, merged against
+ newer arrivals rather than overwritten by the stale retry"
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/ApiKey {api-key-id :id} {::api-keys/unhashed-key "mb_4444444444"
+ :name (mt/random-name)
+ :user_id (mt/user->id :crowberto)
+ :creator_id (mt/user->id :crowberto)
+ :updated_by_id (mt/user->id :crowberto)}]
+ ;; truncated to microseconds to match real DB storage precision; H2 alone preserves nanoseconds.
+ (let [now #(-> (t/instant) (t/truncate-to :micros) (t/offset-date-time (t/zone-offset 0)))
+ earlier (now)
+ later (t/plus earlier (t/seconds 5))
+ route (unique-route)]
+ (try
+ (record! (request-info route :api-key-id api-key-id :occurred-at earlier))
+ ;; simulate the lock step finding every key busy: nothing is actually written
+ (mt/with-dynamic-fn-redefs [api-keys/update-api-keys-last-used-at! (fn [id->timestamp] id->timestamp)]
+ (#'ee-usage/flush-last-used-at!))
+ (is (nil? (last-used-at api-key-id)) "still pending — the redef simulated a busy row")
+ ;; a fresher event lands before the key is retried
+ (record! (request-info route :api-key-id api-key-id :occurred-at later))
+ (#'ee-usage/flush-last-used-at!)
+ (is (= later (last-used-at api-key-id)) "the retried write kept the newer of the two timestamps")
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))
+
+;;; -------------------------------------------- concurrency --------------------------------------------
+;; Real threads, not `synchronous-batch-updates` — exercising the actual concurrent paths (many request
+;; threads racing the in-memory queues, then a flush) rather than simulating them serially.
+
+(deftest concurrent-last-used-at-stamps-keep-the-newest-timestamp-test
+ (testing "many concurrent stamps for one key never lose the newest timestamp to a race"
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/ApiKey {api-key-id :id} {::api-keys/unhashed-key "mb_5555555555"
+ :name (mt/random-name)
+ :user_id (mt/user->id :crowberto)
+ :creator_id (mt/user->id :crowberto)
+ :updated_by_id (mt/user->id :crowberto)}]
+ (let [route (unique-route)
+ ;; truncated to microseconds to match real DB storage precision; H2 alone preserves nanoseconds.
+ base (-> (t/instant) (t/truncate-to :micros) (t/offset-date-time (t/zone-offset 0)))
+ n 50
+ timestamps (mapv #(t/plus base (t/seconds %)) (range n))
+ latest (last timestamps)]
+ (try
+ (run! deref
+ (mapv (fn [ts] (future (record! (request-info route :api-key-id api-key-id :occurred-at ts))))
+ (shuffle timestamps)))
+ (#'ee-usage/flush-last-used-at!)
+ (is (= latest (last-used-at api-key-id)))
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))
+
+(deftest concurrent-usage-log-offers-do-not-lose-rows-test
+ (testing "many concurrent usage-log rows below capacity are never lost to a race in the pending queue"
+ (mt/with-premium-features #{:audit-app}
+ (let [api-key-id 636363
+ n 50
+ routes (mapv #(str (unique-route) "-" %) (range n))]
+ (try
+ (run! deref (mapv (fn [route] (future (record! (request-info route :api-key-id api-key-id)))) routes))
+ (#'ee-usage/flush-usage-logs!)
+ (is (= n (t2/count :model/ApiKeyUsageLog :api_key_id api-key-id)))
+ (finally (t2/delete! :model/ApiKeyUsageLog :api_key_id api-key-id)))))))
+
+;;; ------------------------------------------ flush scheduling ------------------------------------------
+;; JVM-local, not Quartz — see `start-flush!`'s docstring. Both writes coalesce in the same shared atoms
+;; every other test in this namespace uses, so `stop-flush!` (called liberally below) is just the same
+;; force-flush every other test already does, wrapped with idempotent executor teardown.
+
+(deftest start-flush!-is-idempotent-test
+ (testing "a second call shuts down the executor it just created instead of replacing the one already running"
+ (#'ee-usage/stop-flush!) ; clean slate, in case an earlier boot already started the real flush loop
+ (try
+ (is (true? (#'ee-usage/start-flush!)) "the first call creates the executor")
+ (is (false? (#'ee-usage/start-flush!)) "a second call is a no-op")
+ (finally (#'ee-usage/stop-flush!)))))
+
+(deftest stop-flush!-force-flushes-pending-state-test
+ (testing "stop-flush! flushes a pending last_used_at stamp without waiting for the interval"
+ (mt/with-premium-features #{}
+ (mt/with-temp [:model/ApiKey {api-key-id :id} {::api-keys/unhashed-key "mb_9999999999"
+ :name (mt/random-name)
+ :user_id (mt/user->id :crowberto)
+ :creator_id (mt/user->id :crowberto)
+ :updated_by_id (mt/user->id :crowberto)}]
+ (let [route (unique-route)]
+ (try
+ (is (nil? (last-used-at api-key-id)))
+ (record! (request-info route :api-key-id api-key-id))
+ (is (nil? (last-used-at api-key-id)) "not flushed yet — still coalescing")
+ (#'ee-usage/stop-flush!)
+ (is (some? (last-used-at api-key-id)) "stop-flush! force-flushed it")
+ (finally (t2/delete! :model/ApiKeyUsageLog :route_template route))))))))
diff --git a/enterprise/backend/test/metabase_enterprise/api_keys/v_api_key_usage_test.clj b/enterprise/backend/test/metabase_enterprise/api_keys/v_api_key_usage_test.clj
new file mode 100644
index 00000000000..ede1af43759
--- /dev/null
+++ b/enterprise/backend/test/metabase_enterprise/api_keys/v_api_key_usage_test.clj
@@ -0,0 +1,183 @@
+(ns metabase-enterprise.api-keys.v-api-key-usage-test
+ "Tests for the `v_api_key_usage` SQL view. Client identity and PII are stored on each request row;
+ the view derives `client_display_name` from it. Two separate identities: `actor_user_id` is the
+ row's own `user_id` (the key's synthetic service-account user, used for permission checks, never a
+ real person) — `creator_id`/`creator_display_name`/`group_name` come from `created_by_id` (the real
+ human who made the key) and the key's own group (via the key's synthetic user, not the creator's
+ memberships — a key has one group, a creator may have several). The view LEFT JOINs api_key and
+ core_user on purpose — `api_key_usage_log` has no foreign keys, so rows outlive a deleted key or
+ user."
+ (:require
+ [clojure.test :refer [deftest is testing use-fixtures]]
+ [java-time.api :as t]
+ [metabase.api-keys.core :as api-keys]
+ [metabase.api-keys.usage :as api-keys.usage]
+ [metabase.app-db.core :as mdb]
+ [metabase.permissions.core :as perms]
+ [metabase.test :as mt]
+ [metabase.test.fixtures :as fixtures]
+ [toucan2.core :as t2]))
+
+(use-fixtures :once (fixtures/initialize :db))
+
+(set! *warn-on-reflection* true)
+
+(defn- query-view
+ "Query v_api_key_usage, returning only rows for the given log ids."
+ [log-ids]
+ (t2/query {:select [:*]
+ :from [:v_api_key_usage]
+ :where [:in :log_id log-ids]}))
+
+(defn- find-row [rows log-id]
+ (some #(when (= (:log_id %) log-id) %) rows))
+
+(defn- log-row
+ "A minimal `api_key_usage_log` row, with every NOT NULL column filled in."
+ [m]
+ (merge {:api_key_id Integer/MAX_VALUE
+ :route_template "/api/card/:id"
+ :http_method "GET"
+ :status 200
+ :duration_ms 12
+ :client_name "other"
+ :occurred_at (t/offset-date-time)}
+ m))
+
+(deftest joins-and-derived-columns-test
+ (testing "the view separates the key's actor (synthetic user) from its creator, and group_name
+ follows the actor, not the creator"
+ (mt/with-temp
+ [;; the creator: a real human, in a different group from the key itself
+ :model/User {creator-id :id} {:first_name "Ada" :last_name "Lovelace"}
+ :model/PermissionsGroup {creator-group :id} {:name "Admins"}
+ :model/PermissionsGroupMembership _ {:user_id creator-id :group_id creator-group}
+ ;; the key's own synthetic service-account user, in its own (different) group
+ :model/User {actor-id :id} {:first_name "key" :last_name "service-account"}
+ :model/PermissionsGroup {key-group :id} {:name "Analysts"}
+ :model/PermissionsGroupMembership _ {:user_id actor-id :group_id key-group}
+ :model/ApiKey {key-id :id} {::api-keys/unhashed-key "mb_1234567890"
+ :name "Reporting key"
+ :user_id actor-id
+ :creator_id creator-id
+ :updated_by_id creator-id}
+ :model/ApiKeyUsageLog {log-id :id} (log-row {:api_key_id key-id
+ :user_id actor-id
+ :created_by_id creator-id
+ :route_template "/api/card/:id"
+ :http_method "POST"
+ :status 201
+ :duration_ms 42
+ :client_name "metabase-cli"
+ :embedding_client "embedding-sdk-react"
+ :embedding_hostname "example.com"
+ :ip_address "10.0.0.7"
+ :user_agent "metabase-cli/1.2.3"})]
+ (is (=? {:route_template "/api/card/:id"
+ :http_method "POST"
+ :status 201
+ :duration_ms 42
+ :api_key_id key-id
+ :api_key_name "Reporting key"
+ :actor_user_id actor-id
+ :creator_id creator-id
+ :creator_display_name "Ada Lovelace"
+ :group_name "Analysts"
+ :client_name "metabase-cli"
+ :client_display_name "Metabase CLI"
+ :embedding_client "embedding-sdk-react"
+ :embedding_hostname "example.com"
+ :ip_address "10.0.0.7"
+ :user_agent "metabase-cli/1.2.3"}
+ (find-row (query-view [log-id]) log-id))))))
+
+(deftest group-name-falls-back-to-all-users-test
+ (testing "a key whose actor belongs to no group but All Users gets \"All Users\", not a null group_name"
+ (mt/with-temp
+ [;; every new non-tenant user is added to All Users on insert — no explicit membership needed
+ :model/User {creator-id :id} {}
+ :model/User {actor-id :id} {}
+ :model/ApiKey {key-id :id} {::api-keys/unhashed-key "mb_0000000000"
+ :name "All Users only key"
+ :user_id actor-id
+ :creator_id creator-id
+ :updated_by_id creator-id}
+ :model/ApiKeyUsageLog {log-id :id} (log-row {:api_key_id key-id
+ :user_id actor-id
+ :created_by_id creator-id})]
+ (is (= (:name (perms/all-users-group))
+ (:group_name (find-row (query-view [log-id]) log-id)))))))
+
+(deftest missing-key-and-creator-test
+ (testing "a row whose key/creator are gone (or were never set) survives, with null join columns"
+ (mt/with-temp
+ [:model/ApiKeyUsageLog {orphan-id :id} (log-row {:api_key_id Integer/MAX_VALUE
+ :user_id Integer/MAX_VALUE
+ :created_by_id nil})]
+ (let [row (find-row (query-view [orphan-id]) orphan-id)]
+ (is (some? row) "the row is not dropped")
+ (is (=? {:route_template "/api/card/:id"
+ :api_key_id Integer/MAX_VALUE
+ :api_key_name nil
+ :creator_id nil
+ :creator_display_name nil
+ :group_name nil}
+ row))))))
+
+(deftest pii-columns-passthrough-test
+ (testing "ip_address / user_agent pass through as null when PII collection was off at write time"
+ (mt/with-temp
+ [:model/ApiKeyUsageLog {log-id :id} (log-row {:ip_address nil :user_agent nil})]
+ (is (=? {:ip_address nil :user_agent nil :embedding_client nil}
+ (find-row (query-view [log-id]) log-id))))))
+
+(deftest creator-display-name-falls-back-to-email-test
+ (testing "a creator with no last name falls back to their email"
+ (mt/with-temp
+ [:model/User {creator-id :id, email :email} {:first_name "Ada" :last_name nil}
+ :model/ApiKeyUsageLog {log-id :id} (log-row {:created_by_id creator-id})]
+ (is (=? {:creator_display_name email}
+ (find-row (query-view [log-id]) log-id))))))
+
+;; Guard the hand-maintained client_name -> client_display_name coupling. These pairs must stay in
+;; sync with the CASE in the v_api_key_usage view SQL and `supported-client-keys` / `detect-client`
+;; in metabase.api-keys.usage; drift on either side breaks this test rather than silently
+;; mislabeling clients.
+(def ^:private client-name->display-name
+ {"metabase-cli" "Metabase CLI"
+ "curl" "curl"
+ "postman" "Postman"
+ "python-requests" "Python"
+ "r" "R"
+ "node" "Node.js"
+ "other" "Other"})
+
+(deftest client-display-name-mapping-test
+ (testing "the mapping covers exactly the canonical client keys plus the \"other\" catch-all"
+ (is (= (conj api-keys.usage/supported-client-keys "other")
+ (set (keys client-name->display-name)))))
+ (testing "every client_name maps to the expected display name"
+ (doseq [[client-name expected] client-name->display-name]
+ (mt/with-temp
+ [:model/ApiKeyUsageLog {log-id :id} (log-row {:client_name client-name})]
+ (is (= expected (:client_display_name (find-row (query-view [log-id]) log-id)))
+ (format "client_name %s should map to %s" (pr-str client-name) (pr-str expected))))))
+ (testing "an unrecognized client_name passes through unchanged"
+ (mt/with-temp
+ [:model/ApiKeyUsageLog {log-id :id} (log-row {:client_name "brand-new-client"})]
+ (is (= "brand-new-client"
+ (:client_display_name (find-row (query-view [log-id]) log-id)))))))
+
+(deftest creator-display-name-has-a-plain-string-type-on-h2-test
+ (testing "creator_display_name isn't typed VARCHAR_IGNORECASE on H2 (#EMB-2154)"
+ ;; core_user.email is declared VARCHAR_IGNORECASE on H2 for case-insensitive lookups, and
+ ;; COALESCE(name-concat, email) inherits that type. Metabase's H2 type mapper doesn't
+ ;; recognize VARCHAR_IGNORECASE, so it falls back to an unknown column type, and
+ ;; metabase-lib silently excludes unknown-typed columns from the FE's sortable columns —
+ ;; the view's own `CAST(... AS VARCHAR)` is what keeps this column a plain, sortable string.
+ (when (= (mdb/db-type) :h2)
+ (let [column-type (-> (t2/query "SELECT DATA_TYPE FROM INFORMATION_SCHEMA.COLUMNS
+ WHERE TABLE_NAME = 'V_API_KEY_USAGE'
+ AND COLUMN_NAME = 'CREATOR_DISPLAY_NAME'")
+ first :data_type)]
+ (is (not= "VARCHAR_IGNORECASE" column-type))))))
diff --git a/enterprise/backend/test/metabase_enterprise/serialization/models/entity_id_test.clj b/enterprise/backend/test/metabase_enterprise/serialization/models/entity_id_test.clj
index b9d5276befd..d447052bfbc 100644
--- a/enterprise/backend/test/metabase_enterprise/serialization/models/entity_id_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/serialization/models/entity_id_test.clj
@@ -41,6 +41,7 @@
:model/AnalysisFinding
:model/AnalysisFindingError
:model/ApiKey
+ :model/ApiKeyUsageLog
:model/AuthIdentity
:model/ImplicitAction
:model/QueryAction
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationFilters/ConversationFilters.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationFilters/ConversationFilters.tsx
index 18dcafacc35..96393c1735a 100644
--- a/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationFilters/ConversationFilters.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationFilters/ConversationFilters.tsx
@@ -1,3 +1,4 @@
+import type { ReactNode } from "react";
import { useMemo, useState } from "react";
import { P, match } from "ts-pattern";
import { t } from "ttag";
@@ -214,6 +215,11 @@ type ConversationFiltersProps = {
groupOptions: { value: string; label: string }[];
tenantOptions: { value: string; label: string }[];
hasTenants: boolean;
+ /** Hides the user select for pages where filtering by user isn't a meaningful concept. */
+ hasUsers?: boolean;
+ /** Rendered right after the Group select, before User/Date — for a caller-specific filter that
+ * belongs grouped with Group rather than after the rest of this shared bar. */
+ extraFilter?: ReactNode;
};
export function ConversationFilters({
@@ -230,6 +236,8 @@ export function ConversationFilters({
groupOptions,
tenantOptions,
hasTenants,
+ hasUsers = true,
+ extraFilter,
}: ConversationFiltersProps) {
return (
<Flex gap="sm" wrap="wrap" align="center">
@@ -256,15 +264,18 @@ export function ConversationFilters({
bdrs="xs"
data-testid="conversation-filters-group-select"
/>
- <Select
- data={[{ value: "", label: t`All users` }, ...userOptions]}
- value={user ?? ""}
- onChange={(val) => onUserChange(val === "" ? null : val)}
- searchable
- w={FILTER_WIDTH}
- bdrs="xs"
- data-testid="conversation-filters-user-select"
- />
+ {extraFilter}
+ {hasUsers && (
+ <Select
+ data={[{ value: "", label: t`All users` }, ...userOptions]}
+ value={user ?? ""}
+ onChange={(val) => onUserChange(val === "" ? null : val)}
+ searchable
+ w={FILTER_WIDTH}
+ bdrs="xs"
+ data-testid="conversation-filters-user-select"
+ />
+ )}
<ConversationDateFilter value={date} onChange={onDateChange} />
</Flex>
);
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable.ts b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable.ts
index a009fac8ae7..cd1c5fb1b0f 100644
--- a/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable.ts
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable.ts
@@ -19,6 +19,8 @@ type UseAuditTableResult = {
provider: MetadataProvider | null;
table: TableMetadata | CardMetadata | null;
isLoading: boolean;
+ /** A failed metadata request. Without it, a failure looks the same as a view that doesn't exist. */
+ error: unknown;
};
/**
@@ -29,8 +31,11 @@ type UseAuditTableResult = {
* (case-insensitive to handle H2 uppercasing).
*/
export function useAuditTable(viewName: string): UseAuditTableResult {
- const { data: database, isLoading: isLoadingTables } =
- useGetDatabaseMetadataQuery({ id: AUDIT_DB_ID, skip_fields: true });
+ const {
+ data: database,
+ isLoading: isLoadingTables,
+ error: databaseError,
+ } = useGetDatabaseMetadataQuery({ id: AUDIT_DB_ID, skip_fields: true });
const tableId = useMemo(() => {
const lowerName = viewName.toLowerCase();
@@ -55,9 +60,8 @@ export function useAuditTable(viewName: string): UseAuditTableResult {
[provider, table],
);
- const { data: queryMetadata } = useGetAdhocQueryMetadataQuery(
- datasetQuery ?? skipToken,
- );
+ const { data: queryMetadata, error: queryMetadataError } =
+ useGetAdhocQueryMetadataQuery(datasetQuery ?? skipToken);
const isLoadingFields = table != null && queryMetadata == null;
@@ -65,5 +69,6 @@ export function useAuditTable(viewName: string): UseAuditTableResult {
provider,
table: isLoadingFields ? null : table,
isLoading: isLoadingTables || isLoadingFields,
+ error: databaseError ?? queryMetadataError,
};
}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable.unit.spec.tsx
new file mode 100644
index 00000000000..00ae7cca2ff
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable.unit.spec.tsx
@@ -0,0 +1,44 @@
+import fetchMock from "fetch-mock";
+
+import { renderHookWithProviders, waitFor } from "__support__/ui";
+import { createMockDatabase } from "metabase-types/api/mocks";
+
+import { AUDIT_DB_ID } from "../constants";
+
+import { useAuditTable } from "./useAuditTable";
+
+const METADATA_URL = `path:/api/database/${AUDIT_DB_ID}/metadata`;
+
+describe("useAuditTable", () => {
+ it("returns the error when the metadata request fails", async () => {
+ fetchMock.get(METADATA_URL, {
+ status: 500,
+ body: { message: "boom" },
+ });
+
+ const { result } = renderHookWithProviders(
+ () => useAuditTable("v_api_key_usage"),
+ {},
+ );
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.error).toBeDefined();
+ expect(result.current.table).toBeNull();
+ });
+
+ it("returns no error when the lookup succeeds but the view isn't there", async () => {
+ fetchMock.get(
+ METADATA_URL,
+ createMockDatabase({ id: AUDIT_DB_ID, tables: [] }),
+ );
+
+ const { result } = renderHookWithProviders(
+ () => useAuditTable("v_api_key_usage"),
+ {},
+ );
+
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.error).toBeUndefined();
+ expect(result.current.table).toBeNull();
+ });
+});
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyActivityTable.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyActivityTable.tsx
new file mode 100644
index 00000000000..c58ff74f2ce
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyActivityTable.tsx
@@ -0,0 +1,249 @@
+import { useMemo } from "react";
+import { t } from "ttag";
+
+import { useListApiKeysQuery } from "metabase/admin/settings/api/api-key";
+import { DateTime } from "metabase/common/components/DateTime";
+import { LoadingAndErrorWrapper } from "metabase/common/components/LoadingAndErrorWrapper";
+import { MonitorEmptyState } from "metabase/monitor/components/MonitorEmptyState";
+import {
+ Box,
+ Card,
+ Ellipsified,
+ Flex,
+ Skeleton,
+ Text,
+ TreeTable,
+ type TreeTableColumnDef,
+ TreeTableSkeleton,
+ useTreeTableInstance,
+} from "metabase/ui";
+import { EMPTY_CELL_PLACEHOLDER } from "metabase/utils/constants";
+import { useAdhocBreakoutQuery } from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAdhocBreakoutQuery";
+import type { ApiKeyUsageFilters } from "metabase-enterprise/monitor/api-key-usage/query-utils";
+import {
+ apiKeyMatchesScope,
+ buildKeyActivityQuery,
+} from "metabase-enterprise/monitor/api-key-usage/query-utils";
+import type {
+ CardMetadata,
+ MetadataProvider,
+ TableMetadata,
+} from "metabase-lib";
+import type { ApiKey } from "metabase-types/api";
+
+const getNodeId = (apiKey: ApiKey) => String(apiKey.id);
+
+type ApiKeyActivityRow = ApiKey;
+
+/** Most recently active first, keys with no activity in the window last. */
+export function compareByLastUsedAtDesc(
+ a: ApiKeyActivityRow,
+ b: ApiKeyActivityRow,
+): number {
+ if (a.last_used_at == null) {
+ return b.last_used_at == null ? 0 : 1;
+ }
+ if (b.last_used_at == null) {
+ return -1;
+ }
+ return b.last_used_at.localeCompare(a.last_used_at);
+}
+
+type DataSources = {
+ provider: MetadataProvider | null;
+ table: TableMetadata | CardMetadata | null;
+ groupMembersTable: TableMetadata | CardMetadata | null;
+};
+
+type Props = DataSources &
+ ApiKeyUsageFilters & {
+ title: string;
+ h?: number;
+ };
+
+type InnerProps = ApiKeyUsageFilters & {
+ provider: MetadataProvider;
+ table: TableMetadata | CardMetadata;
+ groupMembersTable: TableMetadata | CardMetadata;
+ title: string;
+ h: number;
+};
+
+const TABLE_HEIGHT = 500;
+
+/**
+ * Per-key activity table: name, group, and most recent activity for every API key matching the
+ * page's API key/user/group filters, most recently active first. Which keys appear is decided by
+ * the keys' own metadata from `GET /api/api-key` (id/creator/group), not by activity — a key with
+ * no activity in the selected date window still shows up, with a blank "Last used" cell. The
+ * timestamp itself comes from a `MAX(occurred_at)` breakout over the audit view, scoped to the
+ * same filters as the rest of the page, so it only reflects activity inside the current window.
+ */
+export function ApiKeyActivityTable({
+ provider,
+ table,
+ groupMembersTable,
+ h = TABLE_HEIGHT,
+ ...filters
+}: Props) {
+ if (!provider || !table || !groupMembersTable) {
+ return <Skeleton h={h} />;
+ }
+ return (
+ <ApiKeyActivityTableInner
+ provider={provider}
+ table={table}
+ groupMembersTable={groupMembersTable}
+ h={h}
+ {...filters}
+ />
+ );
+}
+
+function ApiKeyActivityTableInner({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ title,
+ h,
+}: InnerProps) {
+ const {
+ data: apiKeys,
+ isLoading: isLoadingKeys,
+ error: keysError,
+ } = useListApiKeysQuery();
+
+ const activityQuery = useMemo(
+ () =>
+ buildKeyActivityQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ }),
+ [provider, table, groupMembersTable, dateFilter, apiKeyId, userId, groupId],
+ );
+ const {
+ data: activityData,
+ isFetching: isFetchingActivity,
+ error: activityError,
+ } = useAdhocBreakoutQuery(activityQuery);
+
+ // Maps each key with activity in the filtered window to the timestamp of its latest call.
+ const lastActivityByKeyId = useMemo(() => {
+ const cols = activityData?.data?.cols ?? [];
+ const rows = activityData?.data?.rows ?? [];
+ const keyIdIndex = cols.findIndex(
+ (col) => col.name?.toLowerCase() === "api_key_id",
+ );
+ const lastActivityIndex = cols.findIndex(
+ (col) => col.source === "aggregation",
+ );
+ const entries: [number, string | null][] =
+ keyIdIndex < 0 || lastActivityIndex < 0
+ ? []
+ : rows.map((row) => [
+ Number(row[keyIdIndex]),
+ row[lastActivityIndex] == null
+ ? null
+ : String(row[lastActivityIndex]),
+ ]);
+ return new Map(entries);
+ }, [activityData]);
+
+ const rows = useMemo<ApiKeyActivityRow[] | undefined>(
+ () =>
+ apiKeys
+ ?.filter((apiKey) =>
+ apiKeyMatchesScope(apiKey, { apiKeyId, userId, groupId }),
+ )
+ .map((apiKey) => ({
+ ...apiKey,
+ last_used_at: lastActivityByKeyId.get(apiKey.id) ?? undefined,
+ }))
+ .sort(compareByLastUsedAtDesc),
+ [apiKeys, apiKeyId, userId, groupId, lastActivityByKeyId],
+ );
+
+ const columns = useMemo<TreeTableColumnDef<ApiKeyActivityRow>[]>(
+ () => [
+ {
+ id: "name",
+ header: t`Key name`,
+ minWidth: 120,
+ accessorFn: (apiKey) => apiKey.name,
+ cell: ({ row }) => <Ellipsified>{row.original.name}</Ellipsified>,
+ },
+ {
+ id: "group",
+ header: t`Group`,
+ minWidth: 100,
+ accessorFn: (apiKey) => apiKey.group?.name,
+ cell: ({ row }) => (
+ <Ellipsified>{row.original.group?.name}</Ellipsified>
+ ),
+ },
+ {
+ id: "last_used_at",
+ header: t`Last used`,
+ minWidth: 120,
+ accessorFn: (apiKey) => apiKey.last_used_at,
+ sortUndefined: "last",
+ cell: ({ row }) =>
+ row.original.last_used_at ? (
+ <DateTime value={row.original.last_used_at} />
+ ) : (
+ EMPTY_CELL_PLACEHOLDER
+ ),
+ },
+ ],
+ [],
+ );
+
+ const treeTableInstance = useTreeTableInstance<ApiKeyActivityRow>({
+ data: rows ?? [],
+ columns,
+ getNodeId,
+ });
+
+ const isLoading = isLoadingKeys || (isFetchingActivity && !activityData);
+ const error = keysError ?? activityError;
+
+ return (
+ <Card withBorder shadow="none" px="xl" pt="lg" pb="lg" h={h}>
+ <Text fw="bold" mb="lg">
+ {title}
+ </Text>
+ <Box
+ h="calc(100% - 2rem)"
+ style={{ overflow: "auto" }}
+ data-testid="api-key-activity-table"
+ aria-busy={isLoading}
+ >
+ {error ? (
+ <Flex mih="60%" align="center" justify="center">
+ <LoadingAndErrorWrapper loading={false} error={error} />
+ </Flex>
+ ) : isLoading ? (
+ <TreeTableSkeleton
+ columnWidths={columns.map(() => 1 / columns.length)}
+ />
+ ) : (
+ <TreeTable
+ instance={treeTableInstance}
+ hierarchical={false}
+ ariaLabel={t`API keys`}
+ emptyState={<MonitorEmptyState label={t`No key activity`} />}
+ />
+ )}
+ </Box>
+ </Card>
+ );
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyActivityTable.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyActivityTable.unit.spec.ts
new file mode 100644
index 00000000000..4fb8c0e169a
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyActivityTable.unit.spec.ts
@@ -0,0 +1,48 @@
+import type { ApiKey } from "metabase-types/api";
+
+import { compareByLastUsedAtDesc } from "./ApiKeyActivityTable";
+
+const apiKey = (id: number, lastUsedAt: string | null): ApiKey => ({
+ name: `Key ${id}`,
+ id,
+ group: { id: 1, name: "All Users" },
+ creator_id: 1,
+ masked_key: "mb_••••••••1234",
+ created_at: "2026-01-01T00:00:00Z",
+ updated_at: "2026-01-01T00:00:00Z",
+ updated_by: { id: 1, common_name: "Bobby Tables" },
+ last_used_at: lastUsedAt,
+});
+
+describe("compareByLastUsedAtDesc", () => {
+ it("sorts most recently active first", () => {
+ const older = apiKey(1, "2026-01-01T00:00:00Z");
+ const newer = apiKey(2, "2026-02-01T00:00:00Z");
+
+ expect([older, newer].sort(compareByLastUsedAtDesc)).toEqual([
+ newer,
+ older,
+ ]);
+ });
+
+ it("sorts keys with no activity in the window last, regardless of input order", () => {
+ const active = apiKey(1, "2026-01-01T00:00:00Z");
+ const unused = apiKey(2, null);
+
+ expect([unused, active].sort(compareByLastUsedAtDesc)).toEqual([
+ active,
+ unused,
+ ]);
+ expect([active, unused].sort(compareByLastUsedAtDesc)).toEqual([
+ active,
+ unused,
+ ]);
+ });
+
+ it("leaves two unused keys in a stable relative order", () => {
+ const a = apiKey(1, null);
+ const b = apiKey(2, null);
+
+ expect([a, b].sort(compareByLastUsedAtDesc)).toEqual([a, b]);
+ });
+});
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyFilterSelect.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyFilterSelect.tsx
new file mode 100644
index 00000000000..daca0cc826a
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyFilterSelect.tsx
@@ -0,0 +1,48 @@
+import { useMemo } from "react";
+import { t } from "ttag";
+
+import { useListApiKeysQuery } from "metabase/admin/settings/api/api-key";
+import { Select } from "metabase/ui";
+import { apiKeyMatchesScope } from "metabase-enterprise/monitor/api-key-usage/query-utils";
+
+// Matches the width of the shared ConversationFilters selects it sits alongside.
+const FILTER_WIDTH = 205;
+
+type Props = {
+ value: string | null;
+ onChange: (value: string | null) => void;
+ /** Narrows the options to keys in this group — a key belongs to exactly one group. */
+ groupId: number | undefined;
+};
+
+/**
+ * The API key an admin is scoping the page to — the primary dimension of this view (see EMB-2391
+ * discussion), kept separate from the shared `ConversationFilters` bar since that component is also
+ * used by pages with no notion of an API key.
+ */
+export function ApiKeyFilterSelect({ value, onChange, groupId }: Props) {
+ const { data: apiKeys } = useListApiKeysQuery();
+
+ const options = useMemo(
+ () =>
+ (apiKeys ?? [])
+ .filter((apiKey) => apiKeyMatchesScope(apiKey, { groupId }))
+ .map((apiKey) => ({
+ value: String(apiKey.id),
+ label: apiKey.name,
+ })),
+ [apiKeys, groupId],
+ );
+
+ return (
+ <Select
+ data={[{ value: "", label: t`All API keys` }, ...options]}
+ value={value ?? ""}
+ onChange={(val) => onChange(val === "" ? null : val)}
+ searchable
+ w={FILTER_WIDTH}
+ bdrs="xs"
+ data-testid="api-key-usage-filter-select"
+ />
+ );
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageBreakoutChart.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageBreakoutChart.tsx
new file mode 100644
index 00000000000..68ff7ca7fa7
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageBreakoutChart.tsx
@@ -0,0 +1,142 @@
+import { useMemo } from "react";
+import { t } from "ttag";
+
+import { Skeleton, useMantineTheme } from "metabase/ui";
+import { BreakoutChartCard } from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationStatsPage/BreakoutChartCard";
+import { useAdhocBreakoutQuery } from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAdhocBreakoutQuery";
+import type { ApiKeyUsageFilters } from "metabase-enterprise/monitor/api-key-usage/query-utils";
+import { buildCountBreakoutQuery } from "metabase-enterprise/monitor/api-key-usage/query-utils";
+import { toCountBreakoutRawSeries } from "metabase-enterprise/monitor/api-key-usage/raw-series";
+import type {
+ CardMetadata,
+ MetadataProvider,
+ Query,
+ TableMetadata,
+} from "metabase-lib";
+import type { VisualizationDisplay } from "metabase-types/api";
+
+const DEFAULT_CHART_HEIGHT = 350;
+const DEFAULT_MAX_CATEGORIES = 8;
+
+type DataSources = {
+ provider: MetadataProvider | null;
+ table: TableMetadata | CardMetadata | null;
+ groupMembersTable: TableMetadata | CardMetadata | null;
+};
+
+type Props = DataSources &
+ ApiKeyUsageFilters & {
+ title: string;
+ display: VisualizationDisplay;
+ /** Column to break down call counts by (e.g. `client_display_name`, `route_template`). */
+ breakoutColumn: string;
+ maxCategories?: number;
+ h?: number;
+ };
+
+type InnerProps = ApiKeyUsageFilters & {
+ provider: MetadataProvider;
+ table: TableMetadata | CardMetadata;
+ groupMembersTable: TableMetadata | CardMetadata;
+ title: string;
+ display: VisualizationDisplay;
+ breakoutColumn: string;
+ maxCategories: number;
+ h: number;
+};
+
+/**
+ * Single-breakout count chart (e.g. calls by client as a pie, calls by route as a row chart).
+ * Renders a skeleton until the audit metadata is loaded, then delegates to the inner component.
+ */
+export function ApiKeyUsageBreakoutChart({
+ provider,
+ table,
+ groupMembersTable,
+ h = DEFAULT_CHART_HEIGHT,
+ maxCategories = DEFAULT_MAX_CATEGORIES,
+ ...rest
+}: Props) {
+ if (!provider || !table || !groupMembersTable) {
+ return <Skeleton h={h} />;
+ }
+ return (
+ <ApiKeyUsageBreakoutChartInner
+ provider={provider}
+ table={table}
+ groupMembersTable={groupMembersTable}
+ h={h}
+ maxCategories={maxCategories}
+ {...rest}
+ />
+ );
+}
+
+/**
+ * Loaded variant of {@link ApiKeyUsageBreakoutChart}: builds the breakout query, runs it, and
+ * renders the result through the shared chart card. Split out so the query hooks only run once
+ * metadata (provider/table) is available.
+ */
+function ApiKeyUsageBreakoutChartInner({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ title,
+ display,
+ breakoutColumn,
+ maxCategories,
+ h,
+}: InnerProps) {
+ const query = useMemo<Query>(
+ () =>
+ buildCountBreakoutQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ breakoutColumn,
+ }),
+ [
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ breakoutColumn,
+ ],
+ );
+
+ const { data, jsQuery, isFetching } = useAdhocBreakoutQuery(query);
+ const { themeColor } = useMantineTheme().fn;
+
+ const rawSeries = useMemo(
+ () =>
+ toCountBreakoutRawSeries(data, jsQuery, {
+ display,
+ maxCategories,
+ otherLabel: t`Other`,
+ getColor: themeColor,
+ }),
+ [data, jsQuery, display, maxCategories, themeColor],
+ );
+
+ return (
+ <BreakoutChartCard
+ title={title}
+ rawSeries={rawSeries}
+ isFetching={isFetching}
+ display={display}
+ h={h}
+ otherLabel={t`Other`}
+ />
+ );
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageCallsTimelineChart.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageCallsTimelineChart.tsx
new file mode 100644
index 00000000000..82cdb6ad1b7
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageCallsTimelineChart.tsx
@@ -0,0 +1,113 @@
+import { useMemo } from "react";
+import { t } from "ttag";
+
+import { Skeleton, useMantineTheme } from "metabase/ui";
+import { BreakoutChartCard } from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationStatsPage/BreakoutChartCard";
+import { useAdhocBreakoutQuery } from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAdhocBreakoutQuery";
+import type { ApiKeyUsageFilters } from "metabase-enterprise/monitor/api-key-usage/query-utils";
+import { buildCallsByDayQuery } from "metabase-enterprise/monitor/api-key-usage/query-utils";
+import { toCountBreakoutRawSeries } from "metabase-enterprise/monitor/api-key-usage/raw-series";
+import type {
+ CardMetadata,
+ MetadataProvider,
+ TableMetadata,
+} from "metabase-lib";
+
+const CHART_HEIGHT = 320;
+
+type DataSources = {
+ provider: MetadataProvider | null;
+ table: TableMetadata | CardMetadata | null;
+ groupMembersTable: TableMetadata | CardMetadata | null;
+};
+
+type Props = DataSources &
+ ApiKeyUsageFilters & {
+ title: string;
+ h?: number;
+ };
+
+type InnerProps = ApiKeyUsageFilters & {
+ provider: MetadataProvider;
+ table: TableMetadata | CardMetadata;
+ groupMembersTable: TableMetadata | CardMetadata;
+ title: string;
+ h: number;
+};
+
+/**
+ * Line chart of total calls per day. Renders a skeleton until the audit metadata is loaded, then
+ * delegates to the inner component.
+ */
+export function ApiKeyUsageCallsTimelineChart({
+ provider,
+ table,
+ groupMembersTable,
+ title,
+ h = CHART_HEIGHT,
+ ...filters
+}: Props) {
+ if (!provider || !table || !groupMembersTable) {
+ return <Skeleton h={h} />;
+ }
+ return (
+ <ApiKeyUsageCallsTimelineChartInner
+ provider={provider}
+ table={table}
+ groupMembersTable={groupMembersTable}
+ title={title}
+ h={h}
+ {...filters}
+ />
+ );
+}
+
+function ApiKeyUsageCallsTimelineChartInner({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ title,
+ h,
+}: InnerProps) {
+ const query = useMemo(
+ () =>
+ buildCallsByDayQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ }),
+ [provider, table, groupMembersTable, dateFilter, apiKeyId, userId, groupId],
+ );
+
+ const { data, jsQuery, isFetching } = useAdhocBreakoutQuery(query);
+ const { themeColor } = useMantineTheme().fn;
+
+ const rawSeries = useMemo(
+ () =>
+ toCountBreakoutRawSeries(data, jsQuery, {
+ display: "line",
+ otherLabel: t`Other`,
+ getColor: themeColor,
+ }),
+ [data, jsQuery, themeColor],
+ );
+
+ return (
+ <BreakoutChartCard
+ title={title}
+ rawSeries={rawSeries}
+ isFetching={isFetching}
+ display="line"
+ h={h}
+ otherLabel={t`Other`}
+ />
+ );
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEmptyState.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEmptyState.tsx
new file mode 100644
index 00000000000..60a8f2d3a83
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEmptyState.tsx
@@ -0,0 +1,17 @@
+import { t } from "ttag";
+
+import { EmptyState } from "metabase/common/components/EmptyState";
+import { Flex } from "metabase/ui";
+
+/** Centered placeholder shown (in place of the tabs/charts) when the filtered view has no calls. */
+export function ApiKeyUsageEmptyState() {
+ return (
+ <Flex flex={1} mih="60vh" align="center" justify="center">
+ <EmptyState
+ icon="key"
+ title={t`No API key activity`}
+ message={t`Requests authenticated with an API key will show up here. Try widening the date range or check back once a key is used.`}
+ />
+ </Flex>
+ );
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEventsPage.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEventsPage.tsx
new file mode 100644
index 00000000000..08a0230d1d7
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEventsPage.tsx
@@ -0,0 +1,33 @@
+import { ApiKeyUsageEventsTable } from "./ApiKeyUsageEventsTable";
+import { useApiKeyUsageContext } from "./context";
+
+export function ApiKeyUsageEventsPage() {
+ const {
+ dataSources: { provider, table, groupMembersTable },
+ chartFilters: { dateFilter, apiKeyId, userId, groupId },
+ hasPii,
+ page,
+ total,
+ onPageChange,
+ sortingOptions,
+ onSortingOptionsChange,
+ } = useApiKeyUsageContext();
+
+ return (
+ <ApiKeyUsageEventsTable
+ provider={provider}
+ table={table}
+ groupMembersTable={groupMembersTable}
+ dateFilter={dateFilter}
+ apiKeyId={apiKeyId}
+ userId={userId}
+ groupId={groupId}
+ hasPii={hasPii}
+ page={page}
+ total={total}
+ onPageChange={onPageChange}
+ sortingOptions={sortingOptions}
+ onSortingOptionsChange={onSortingOptionsChange}
+ />
+ );
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEventsTable.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEventsTable.tsx
new file mode 100644
index 00000000000..9b291f961b9
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageEventsTable.tsx
@@ -0,0 +1,354 @@
+import { type ReactNode, useMemo } from "react";
+import { t } from "ttag";
+
+import { DateTime } from "metabase/common/components/DateTime";
+import { LoadingAndErrorWrapper } from "metabase/common/components/LoadingAndErrorWrapper";
+import { PaginationControls } from "metabase/common/components/PaginationControls";
+import { useScrollToTop, useSortingStateChange } from "metabase/common/hooks";
+import { MonitorEmptyState } from "metabase/monitor/components/MonitorEmptyState";
+import { MonitorTableCard } from "metabase/monitor/components/MonitorTableCard";
+import {
+ Box,
+ Ellipsified,
+ Flex,
+ LoadingOverlay,
+ Stack,
+ TreeTable,
+ type TreeTableColumnDef,
+ TreeTableSkeleton,
+ useTreeTableInstance,
+} from "metabase/ui";
+import { EMPTY_CELL_PLACEHOLDER } from "metabase/utils/constants";
+import { formatNumber } from "metabase/utils/formatting";
+import { useApiKeyUsageEventsQuery } from "metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageEventsQuery";
+import {
+ API_KEY_USAGE_EVENT_SORT_COLUMNS,
+ type ApiKeyUsageEventSortColumn,
+ type ApiKeyUsageFilters,
+ apiKeyUsageEventColumnKeys,
+ buildEventsQuery,
+} from "metabase-enterprise/monitor/api-key-usage/query-utils";
+import type {
+ CardMetadata,
+ MetadataProvider,
+ TableMetadata,
+} from "metabase-lib";
+import type { RowValue, RowValues, SortingOptions } from "metabase-types/api";
+
+export const EVENTS_PAGE_SIZE = 25;
+
+const DEFAULT_SORTING: SortingOptions<ApiKeyUsageEventSortColumn> = {
+ sort_column: "occurred_at",
+ sort_direction: "desc",
+};
+
+type EventColumn = {
+ key: ApiKeyUsageEventSortColumn;
+ title: string;
+ sort?: ApiKeyUsageEventSortColumn;
+ align?: "right";
+ grow?: boolean;
+ /** Overrides the default auto-width cap — for columns whose content doesn't fit in 200px. */
+ maxAutoWidth?: number;
+ render?: (value: RowValue) => ReactNode;
+};
+
+const EVENT_COLUMN_META: Record<
+ ApiKeyUsageEventSortColumn,
+ () => Omit<EventColumn, "key">
+> = {
+ log_id: () => ({ title: t`ID`, sort: "log_id" }),
+ occurred_at: () => ({
+ title: t`Occurred at`,
+ sort: "occurred_at",
+ maxAutoWidth: 240,
+ render: (value) =>
+ value == null ? (
+ EMPTY_CELL_PLACEHOLDER
+ ) : (
+ <DateTime value={String(value)} />
+ ),
+ }),
+ route_template: () => ({
+ title: t`Route`,
+ sort: "route_template",
+ grow: true,
+ render: (value) =>
+ value == null ? (
+ EMPTY_CELL_PLACEHOLDER
+ ) : (
+ <Ellipsified>{String(value)}</Ellipsified>
+ ),
+ }),
+ http_method: () => ({ title: t`Method`, sort: "http_method" }),
+ status: () => ({ title: t`Status`, sort: "status", align: "right" }),
+ duration_ms: () => ({
+ title: t`Duration (ms)`,
+ sort: "duration_ms",
+ align: "right",
+ render: (value) =>
+ value == null ? EMPTY_CELL_PLACEHOLDER : formatNumber(Number(value)),
+ }),
+ api_key_name: () => ({ title: t`API key`, sort: "api_key_name" }),
+ creator_display_name: () => ({
+ title: t`Created by`,
+ sort: "creator_display_name",
+ }),
+ client_display_name: () => ({
+ title: t`Client`,
+ sort: "client_display_name",
+ }),
+ embedding_client: () => ({
+ title: t`Embedding client`,
+ sort: "embedding_client",
+ }),
+ embedding_hostname: () => ({
+ title: t`Embedding hostname`,
+ sort: "embedding_hostname",
+ }),
+ ip_address: () => ({ title: t`IP address`, sort: "ip_address" }),
+};
+
+export function eventColumns(hasPii: boolean): EventColumn[] {
+ return apiKeyUsageEventColumnKeys(hasPii).map((key) => ({
+ key,
+ ...EVENT_COLUMN_META[key](),
+ }));
+}
+
+function renderCell(column: EventColumn, value: RowValue): ReactNode {
+ if (column.render) {
+ return column.render(value);
+ }
+ return value == null || value === "" ? EMPTY_CELL_PLACEHOLDER : String(value);
+}
+
+type EventRow = { id: string } & Record<string, RowValue>;
+
+type PaginationProps = {
+ page: number;
+ total: number;
+ onPageChange: (page: number) => void;
+};
+
+type SortProps = {
+ sortingOptions: SortingOptions<ApiKeyUsageEventSortColumn>;
+ onSortingOptionsChange: (
+ sortingOptions: SortingOptions<ApiKeyUsageEventSortColumn>,
+ ) => void;
+};
+
+type Nullable<T> = { [K in keyof T]: T[K] | null };
+
+type MetadataSources = {
+ provider: MetadataProvider;
+ table: TableMetadata | CardMetadata;
+ groupMembersTable: TableMetadata | CardMetadata;
+};
+
+type BaseProps = ApiKeyUsageFilters &
+ PaginationProps &
+ SortProps & {
+ hasPii: boolean;
+ };
+
+type Props = BaseProps & Nullable<MetadataSources>;
+type InnerProps = BaseProps & MetadataSources;
+
+export function ApiKeyUsageEventsTable({
+ provider,
+ table,
+ groupMembersTable,
+ ...rest
+}: Props) {
+ if (!provider || !table || !groupMembersTable) {
+ return null;
+ }
+ return (
+ <ApiKeyUsageEventsTableInner
+ provider={provider}
+ table={table}
+ groupMembersTable={groupMembersTable}
+ {...rest}
+ />
+ );
+}
+
+function ApiKeyUsageEventsTableInner({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ hasPii,
+ page,
+ total,
+ onPageChange,
+ sortingOptions,
+ onSortingOptionsChange,
+}: InnerProps) {
+ const columns = useMemo(() => eventColumns(hasPii), [hasPii]);
+
+ const { sort_column: sortColumn, sort_direction: sortDirection } =
+ sortingOptions;
+ const effectiveSorting = useMemo(() => {
+ const visibleSortColumns = new Set(
+ columns.map((column) => column.sort).filter(Boolean),
+ );
+ return visibleSortColumns.has(sortColumn)
+ ? { sort_column: sortColumn, sort_direction: sortDirection }
+ : DEFAULT_SORTING;
+ }, [columns, sortColumn, sortDirection]);
+
+ const query = useMemo(
+ () =>
+ buildEventsQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ sortColumn: effectiveSorting.sort_column,
+ sortDirection: effectiveSorting.sort_direction,
+ hasPii,
+ }),
+ [
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ effectiveSorting,
+ hasPii,
+ ],
+ );
+
+ const { data, isFetching, error } = useApiKeyUsageEventsQuery(
+ query,
+ page,
+ EVENTS_PAGE_SIZE,
+ );
+
+ // The result columns (`data.data.cols`) are the full, warehouse-ordered set the query returns —
+ // not the curated `columns` we render. So we map each curated column to its position in the
+ // result by name. Names are upper- or lower-cased depending on the warehouse, so match case-insensitively.
+ const columnIndex = useMemo(() => {
+ const cols = data?.data?.cols ?? [];
+ return new Map(cols.map((col, index) => [col.name.toLowerCase(), index]));
+ }, [data]);
+
+ const rows: EventRow[] = useMemo(() => {
+ const rawRows: RowValues[] = data?.data?.rows ?? [];
+ return rawRows.map((rawRow, rowIndex) => {
+ const values = Object.fromEntries(
+ columns.map((column) => {
+ const index = columnIndex.get(column.key);
+ return [column.key, index != null ? rawRow[index] : null];
+ }),
+ );
+ const id = String(values.log_id ?? `${page}-${rowIndex}`);
+ return { id, ...values };
+ });
+ }, [data, columns, columnIndex, page]);
+
+ const treeColumns = useMemo<TreeTableColumnDef<EventRow>[]>(
+ () =>
+ columns.map((column) => ({
+ id: column.key,
+ header: column.title,
+ ...(column.grow
+ ? { minWidth: 280 }
+ : {
+ width: "auto" as const,
+ minWidth: 120,
+ maxAutoWidth: column.maxAutoWidth ?? 200,
+ }),
+ enableSorting: !!column.sort,
+ sortDescFirst: column.sort === "occurred_at",
+ accessorFn: (row) => row[column.key],
+ cell: ({ row }) => {
+ const node = renderCell(column, row.original[column.key]);
+ return column.align === "right" ? (
+ <Box ta="right" w="100%">
+ {node}
+ </Box>
+ ) : (
+ node
+ );
+ },
+ })),
+ [columns],
+ );
+
+ const { sortingState, onSortingChange } = useSortingStateChange({
+ sortingOptions: effectiveSorting,
+ columns: API_KEY_USAGE_EVENT_SORT_COLUMNS,
+ defaultSorting: DEFAULT_SORTING,
+ onSortingOptionsChange,
+ });
+
+ const treeTableInstance = useTreeTableInstance<EventRow>({
+ data: rows,
+ columns: treeColumns,
+ sorting: sortingState,
+ manualSorting: true,
+ getNodeId: (row) => row.id,
+ onSortingChange,
+ });
+
+ useScrollToTop({
+ ref: treeTableInstance.containerRef,
+ keys: [page, effectiveSorting],
+ skip: isFetching,
+ });
+
+ const skeletonColumnWidths = columns.map(() => 1 / columns.length);
+
+ return (
+ <Stack gap="lg" flex={1} mih={0}>
+ <MonitorTableCard
+ aria-busy={isFetching}
+ data-testid="api-key-usage-events-table"
+ >
+ {error ? (
+ <Flex mih="60vh" align="center" justify="center">
+ <LoadingAndErrorWrapper loading={false} error={error} />
+ </Flex>
+ ) : !data ? (
+ <TreeTableSkeleton columnWidths={skeletonColumnWidths} />
+ ) : (
+ <>
+ <LoadingOverlay visible={isFetching} />
+ <TreeTable
+ instance={treeTableInstance}
+ hierarchical={false}
+ ariaLabel={t`Calls`}
+ emptyState={<MonitorEmptyState label={t`No calls found`} />}
+ getRowProps={() => ({ "data-testid": "api-key-usage-event" })}
+ />
+ </>
+ )}
+ </MonitorTableCard>
+
+ {data && !error && (
+ <Flex justify="flex-end">
+ <PaginationControls
+ page={page}
+ pageSize={EVENTS_PAGE_SIZE}
+ itemsLength={rows.length}
+ total={total}
+ showTotal
+ onPreviousPage={() => onPageChange(page - 1)}
+ onNextPage={() => onPageChange(page + 1)}
+ />
+ </Flex>
+ )}
+ </Stack>
+ );
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsagePage.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsagePage.tsx
new file mode 100644
index 00000000000..4652f9a5940
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsagePage.tsx
@@ -0,0 +1,69 @@
+import { t } from "ttag";
+
+import { SimpleGrid, Stack } from "metabase/ui";
+
+import { ApiKeyActivityTable } from "./ApiKeyActivityTable";
+import { ApiKeyUsageBreakoutChart } from "./ApiKeyUsageBreakoutChart";
+import { ApiKeyUsageCallsTimelineChart } from "./ApiKeyUsageCallsTimelineChart";
+import { useApiKeyUsageContext } from "./context";
+
+export function ApiKeyUsagePage() {
+ const {
+ dataSources: { provider, table, groupMembersTable },
+ chartFilters: { dateFilter, apiKeyId, userId, groupId },
+ } = useApiKeyUsageContext();
+
+ return (
+ <Stack gap="xl">
+ <ApiKeyActivityTable
+ provider={provider}
+ table={table}
+ groupMembersTable={groupMembersTable}
+ dateFilter={dateFilter}
+ apiKeyId={apiKeyId}
+ userId={userId}
+ groupId={groupId}
+ title={t`Key activity`}
+ h={500}
+ />
+ <ApiKeyUsageCallsTimelineChart
+ provider={provider}
+ table={table}
+ groupMembersTable={groupMembersTable}
+ dateFilter={dateFilter}
+ apiKeyId={apiKeyId}
+ userId={userId}
+ groupId={groupId}
+ title={t`Calls over time`}
+ />
+ <SimpleGrid cols={2} spacing="xl">
+ <ApiKeyUsageBreakoutChart
+ provider={provider}
+ table={table}
+ groupMembersTable={groupMembersTable}
+ dateFilter={dateFilter}
+ apiKeyId={apiKeyId}
+ userId={userId}
+ groupId={groupId}
+ title={t`Calls by client`}
+ display="pie"
+ breakoutColumn="client_display_name"
+ h={500}
+ />
+ <ApiKeyUsageBreakoutChart
+ provider={provider}
+ table={table}
+ groupMembersTable={groupMembersTable}
+ dateFilter={dateFilter}
+ apiKeyId={apiKeyId}
+ userId={userId}
+ groupId={groupId}
+ title={t`Calls by route`}
+ display="row"
+ breakoutColumn="route_template"
+ h={500}
+ />
+ </SimpleGrid>
+ </Stack>
+ );
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageSectionLayout.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageSectionLayout.tsx
new file mode 100644
index 00000000000..91a4deb22ed
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/ApiKeyUsageSectionLayout.tsx
@@ -0,0 +1,277 @@
+import type { ReactNode } from "react";
+import { useMemo } from "react";
+import { t } from "ttag";
+
+import { useListApiKeysQuery } from "metabase/admin/settings/api/api-key";
+import { LoadingAndErrorWrapper } from "metabase/common/components/LoadingAndErrorWrapper";
+import {
+ type PillTab,
+ PillTabNavigation,
+} from "metabase/common/components/PillTabNavigation";
+import { useUrlState } from "metabase/common/hooks/use-url-state";
+import { MonitorHeaderTitle } from "metabase/monitor/components/MonitorHeaderTitle";
+import { MonitorMain } from "metabase/monitor/components/MonitorLayout";
+import { Outlet, useLocation } from "metabase/router";
+import { useSetting } from "metabase/settings";
+import { Flex, Loader, Stack } from "metabase/ui";
+import * as Urls from "metabase/urls";
+import {
+ ConversationFilters as ApiKeyUsageFilterBar,
+ parseId,
+ useFilterOptions,
+} from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationFilters";
+import { useAuditTable } from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAuditTable";
+import {
+ VIEW_API_KEY_USAGE,
+ VIEW_GROUP_MEMBERS,
+} from "metabase-enterprise/monitor/api-key-usage/constants";
+import { useApiKeyUsageHasData } from "metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageHasData";
+import { isKeyOutsideGroup } from "metabase-enterprise/monitor/api-key-usage/query-utils";
+import { apiKeyUsageUrlStateConfig } from "metabase-enterprise/monitor/api-key-usage/url-state";
+
+import { ApiKeyFilterSelect } from "./ApiKeyFilterSelect";
+import { ApiKeyUsageEmptyState } from "./ApiKeyUsageEmptyState";
+import {
+ ApiKeyUsageContextProvider,
+ type ApiKeyUsageContextValue,
+} from "./context";
+
+type RouteContentProps = {
+ children: ReactNode;
+ error: unknown;
+ isInitialLoading: boolean;
+};
+
+function RouteContent({
+ children,
+ error,
+ isInitialLoading,
+}: RouteContentProps) {
+ if (error !== undefined && error !== null) {
+ return (
+ <Flex mih="60vh" align="center" justify="center">
+ <LoadingAndErrorWrapper loading={false} error={error} />
+ </Flex>
+ );
+ }
+
+ if (isInitialLoading) {
+ return (
+ <Flex mih="60vh" align="center" justify="center">
+ <Loader size="lg" />
+ </Flex>
+ );
+ }
+
+ return children;
+}
+
+export function ApiKeyUsageSectionLayout() {
+ const location = useLocation();
+ const [
+ { date, user, group, tenant, api_key, page, sort_column, sort_direction },
+ { patchUrlState },
+ ] = useUrlState(location, apiKeyUsageUrlStateConfig);
+
+ const {
+ dateFilter,
+ userId,
+ groupId,
+ groupNoFilterValue,
+ userOptions,
+ groupOptions,
+ } = useFilterOptions({ date, user, group, tenant });
+
+ const { data: apiKeys } = useListApiKeysQuery();
+ const selectedApiKey = useMemo(
+ () => apiKeys?.find((apiKey) => apiKey.id === parseId(api_key)),
+ [apiKeys, api_key],
+ );
+ // Group and API key work like State and City: Group is only ever set by the user, the key list
+ // is narrowed to the chosen group, and picking another group clears a key that isn't in it. The
+ // UI can't produce a key outside the group, but a stale or hand-edited URL can — ignore the key
+ // then, rather than let the two filters silently return nothing.
+ const keyOutsideGroup = isKeyOutsideGroup(selectedApiKey, groupId);
+ const apiKeyId = keyOutsideGroup ? undefined : parseId(api_key);
+
+ const hasPii = useSetting("analytics-pii-retention-enabled") === true;
+ const usageAudit = useAuditTable(VIEW_API_KEY_USAGE);
+ const groupMembersAudit = useAuditTable(VIEW_GROUP_MEMBERS);
+
+ const dataSources = useMemo(
+ () => ({
+ provider: usageAudit.provider,
+ table: usageAudit.table,
+ groupMembersTable: groupMembersAudit.table,
+ }),
+ [usageAudit.provider, usageAudit.table, groupMembersAudit.table],
+ );
+ const chartFilters = useMemo(
+ () => ({ dateFilter, apiKeyId, userId, groupId }),
+ [apiKeyId, dateFilter, groupId, userId],
+ );
+ const sortingOptions = useMemo(
+ () => ({ sort_column, sort_direction }),
+ [sort_column, sort_direction],
+ );
+
+ const {
+ isInitialLoading,
+ isRefetching,
+ hasData,
+ count,
+ error,
+ tablesMissing,
+ } = useApiKeyUsageHasData({
+ ...dataSources,
+ ...chartFilters,
+ isLoadingTables: usageAudit.isLoading || groupMembersAudit.isLoading,
+ });
+ // `tablesMissing` wins over `hasData`: the charts and tables below can't do anything useful
+ // with a null table either — they'd just sit on their own skeletons forever — so show the
+ // empty state instead of rendering them once the lookup has settled as missing.
+ const showEmpty =
+ !isInitialLoading && !isRefetching && (!hasData || tablesMissing);
+
+ const usagePath = Urls.monitorApiKeyUsageOverview();
+ const eventsPath = Urls.monitorApiKeyUsageEvents();
+ const tabs: PillTab[] = [
+ {
+ label: t`Usage`,
+ to: `${usagePath}${location.search}`,
+ isSelected: (pathname) => pathname === usagePath,
+ },
+ {
+ label: t`Events`,
+ to: `${eventsPath}${location.search}`,
+ isSelected: (pathname) => pathname === eventsPath,
+ },
+ ];
+
+ const isTableRoute = location.pathname === eventsPath;
+ const outletContext = useMemo<ApiKeyUsageContextValue>(
+ () => ({
+ dataSources,
+ chartFilters,
+ hasPii,
+ page,
+ total: count,
+ onPageChange: (newPage) =>
+ patchUrlState({ page: newPage }, { immediate: true }),
+ sortingOptions,
+ onSortingOptionsChange: (newSorting) =>
+ patchUrlState({
+ sort_column: newSorting.sort_column,
+ sort_direction: newSorting.sort_direction,
+ page: 0,
+ }),
+ }),
+ [
+ chartFilters,
+ count,
+ dataSources,
+ hasPii,
+ page,
+ patchUrlState,
+ sortingOptions,
+ ],
+ );
+
+ // Tabs + filters stay outside the scrollable area below (rendered once per branch, same
+ // elements, just never scrolled past) so they're always visible regardless of page length.
+ const tabsAndFilters = (
+ <>
+ <PillTabNavigation tabs={tabs} />
+ <ApiKeyUsageFilterBar
+ date={date}
+ onDateChange={(val) => patchUrlState({ date: val, page: 0 })}
+ user={user}
+ onUserChange={(val) => patchUrlState({ user: val, page: 0 })}
+ userOptions={userOptions}
+ group={group}
+ onGroupChange={(val) =>
+ patchUrlState({
+ group: val,
+ // Like picking a new State: a key that isn't in the new group is cleared.
+ ...(isKeyOutsideGroup(
+ selectedApiKey,
+ val == null ? null : Number(val),
+ )
+ ? { api_key: null }
+ : {}),
+ page: 0,
+ })
+ }
+ groupOptions={groupOptions}
+ groupNoFilterValue={groupNoFilterValue}
+ // Tenants aren't a meaningful concept for API-key usage — see EMB-2391, which will make
+ // this shared filter bar's tenant support properly optional instead of hardcoded off here.
+ tenant={null}
+ onTenantChange={() => {}}
+ tenantOptions={[]}
+ hasTenants={false}
+ // The API key filter (below) is the primary way to scope this page; a separate user
+ // filter is redundant now that "Created by" is just a column.
+ hasUsers={false}
+ extraFilter={
+ <ApiKeyFilterSelect
+ value={keyOutsideGroup ? null : api_key}
+ onChange={(val) => patchUrlState({ api_key: val, page: 0 })}
+ groupId={groupId}
+ />
+ }
+ />
+ </>
+ );
+
+ const pageContent = (
+ <RouteContent
+ error={error ?? usageAudit.error ?? groupMembersAudit.error}
+ isInitialLoading={isInitialLoading}
+ >
+ {showEmpty ? (
+ <ApiKeyUsageEmptyState />
+ ) : (
+ <ApiKeyUsageContextProvider value={outletContext}>
+ <Outlet />
+ </ApiKeyUsageContextProvider>
+ )}
+ </RouteContent>
+ );
+
+ if (isTableRoute) {
+ return (
+ <Flex h="100%" wrap="nowrap">
+ <MonitorMain>
+ <Stack gap="xl" flex={1} mih={0}>
+ <MonitorHeaderTitle>{t`API key usage`}</MonitorHeaderTitle>
+ {tabsAndFilters}
+ <Stack
+ gap="lg"
+ flex={1}
+ mih={0}
+ display="flex"
+ style={{ flexDirection: "column" }}
+ >
+ {pageContent}
+ </Stack>
+ </Stack>
+ </MonitorMain>
+ </Flex>
+ );
+ }
+
+ return (
+ <Flex h="100%" wrap="nowrap">
+ <MonitorMain>
+ <Stack gap="xl" flex={1} mih={0}>
+ <MonitorHeaderTitle>{t`API key usage`}</MonitorHeaderTitle>
+ {tabsAndFilters}
+ <Stack gap="lg" flex={1} mih={0} style={{ overflowY: "auto" }}>
+ {pageContent}
+ </Stack>
+ </Stack>
+ </MonitorMain>
+ </Flex>
+ );
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/context.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/context.tsx
new file mode 100644
index 00000000000..12ed8fac72c
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/context.tsx
@@ -0,0 +1,59 @@
+import { type ReactNode, createContext, useContext } from "react";
+
+import type {
+ ApiKeyUsageEventSortColumn,
+ ApiKeyUsageFilters,
+} from "metabase-enterprise/monitor/api-key-usage/query-utils";
+import type {
+ CardMetadata,
+ MetadataProvider,
+ TableMetadata,
+} from "metabase-lib";
+import type { SortingOptions } from "metabase-types/api";
+
+type ApiKeyUsageDataSources = {
+ provider: MetadataProvider | null;
+ table: TableMetadata | CardMetadata | null;
+ groupMembersTable: TableMetadata | CardMetadata | null;
+};
+
+export type ApiKeyUsageContextValue = {
+ dataSources: ApiKeyUsageDataSources;
+ chartFilters: ApiKeyUsageFilters;
+ hasPii: boolean;
+ page: number;
+ total: number;
+ onPageChange: (page: number) => void;
+ sortingOptions: SortingOptions<ApiKeyUsageEventSortColumn>;
+ onSortingOptionsChange: (
+ sortingOptions: SortingOptions<ApiKeyUsageEventSortColumn>,
+ ) => void;
+};
+
+const ApiKeyUsageContext = createContext<ApiKeyUsageContextValue | null>(null);
+
+type ApiKeyUsageContextProviderProps = {
+ children: ReactNode;
+ value: ApiKeyUsageContextValue;
+};
+
+export function ApiKeyUsageContextProvider({
+ children,
+ value,
+}: ApiKeyUsageContextProviderProps) {
+ return (
+ <ApiKeyUsageContext.Provider value={value}>
+ {children}
+ </ApiKeyUsageContext.Provider>
+ );
+}
+
+export function useApiKeyUsageContext(): ApiKeyUsageContextValue {
+ const context = useContext(ApiKeyUsageContext);
+ if (context === null) {
+ throw new Error(
+ "useApiKeyUsageContext must be used within ApiKeyUsageContextProvider",
+ );
+ }
+ return context;
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/index.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/index.ts
new file mode 100644
index 00000000000..8c1d801f555
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/components/index.ts
@@ -0,0 +1,3 @@
+export { ApiKeyUsageSectionLayout } from "./ApiKeyUsageSectionLayout";
+export { ApiKeyUsagePage } from "./ApiKeyUsagePage";
+export { ApiKeyUsageEventsPage } from "./ApiKeyUsageEventsPage";
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/constants.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/constants.ts
new file mode 100644
index 00000000000..07bda4214bd
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/constants.ts
@@ -0,0 +1,7 @@
+export {
+ AUDIT_DB_ID,
+ VIEW_GROUP_MEMBERS,
+} from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/constants";
+
+// View name in the audit database for API key usage analytics.
+export const VIEW_API_KEY_USAGE = "v_api_key_usage";
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageEventsQuery.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageEventsQuery.ts
new file mode 100644
index 00000000000..3a51ab376c1
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageEventsQuery.ts
@@ -0,0 +1,36 @@
+import { useMemo } from "react";
+
+import { skipToken, useGetAdhocQueryQuery } from "metabase/api";
+import { paginateEventsQuery } from "metabase-enterprise/monitor/api-key-usage/query-utils";
+import type { Query } from "metabase-lib";
+import * as Lib from "metabase-lib";
+import type { Dataset } from "metabase-types/api";
+
+type EventsPageResult = {
+ data: Dataset | undefined;
+ isFetching: boolean;
+ error: unknown;
+};
+
+/**
+ * Run the row-level events query for one page. Applies the MBQL `:page` clause (via
+ * {@link paginateEventsQuery}) before execution so the backend returns only the requested page.
+ * `page` is 0-indexed.
+ */
+export function useApiKeyUsageEventsQuery(
+ query: Query | null,
+ page: number,
+ pageSize: number,
+): EventsPageResult {
+ const jsQuery = useMemo(
+ () =>
+ query ? Lib.toJsQuery(paginateEventsQuery(query, page, pageSize)) : null,
+ [query, page, pageSize],
+ );
+
+ const { data, isFetching, error } = useGetAdhocQueryQuery(
+ jsQuery ?? skipToken,
+ );
+
+ return { data, isFetching, error };
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageHasData.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageHasData.ts
new file mode 100644
index 00000000000..ccae1738b34
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageHasData.ts
@@ -0,0 +1,167 @@
+import { useMemo, useRef } from "react";
+
+import { useListApiKeysQuery } from "metabase/admin/settings/api/api-key";
+import { useAdhocBreakoutQuery } from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/hooks/useAdhocBreakoutQuery";
+import type { ApiKeyUsageFilters } from "metabase-enterprise/monitor/api-key-usage/query-utils";
+import {
+ apiKeyMatchesScope,
+ buildTotalCountQuery,
+} from "metabase-enterprise/monitor/api-key-usage/query-utils";
+import type {
+ CardMetadata,
+ MetadataProvider,
+ TableMetadata,
+} from "metabase-lib";
+
+type DataSources = {
+ provider: MetadataProvider | null;
+ table: TableMetadata | CardMetadata | null;
+ groupMembersTable: TableMetadata | CardMetadata | null;
+ /** Whether the `table`/`groupMembersTable` lookup itself (view name -> table metadata) is
+ * still resolving — distinct from the data queries below, which only start once this settles.
+ * Without this, a view the audit db hasn't synced yet would leave `table` null and `query`
+ * null forever, and the page would spin forever with no escape hatch. */
+ isLoadingTables: boolean;
+};
+
+type ResolvedArgs = {
+ /** Whether the `table`/`groupMembersTable` lookup itself is still resolving. */
+ isLoadingTables: boolean;
+ isFetching: boolean;
+ isFetchingKeys: boolean;
+ /** Null means either still loading the tables, or the tables were never found. */
+ query: unknown;
+ data: unknown;
+ apiKeys: unknown;
+ hasError: boolean;
+};
+
+/**
+ * Whether every input this hook depends on has settled, one way or another. Once the table
+ * lookup is done, a still-null `query` means the view genuinely isn't there to query (nothing
+ * more to wait for) rather than still loading — treated the same as a resolved, empty count.
+ * Without that distinction, a view the audit db hasn't synced yet would leave `query` null
+ * forever, and the page would spin forever with no escape hatch.
+ */
+export function isResolved({
+ isLoadingTables,
+ isFetching,
+ isFetchingKeys,
+ query,
+ data,
+ apiKeys,
+ hasError,
+}: ResolvedArgs): boolean {
+ return (
+ !isLoadingTables &&
+ !isFetching &&
+ !isFetchingKeys &&
+ apiKeys !== undefined &&
+ (query === null || data !== undefined || hasError)
+ );
+}
+
+type Result = {
+ /** First load, before the count has ever resolved — show a loader, never the empty state. */
+ isInitialLoading: boolean;
+ /** A subsequent load triggered by a filter change — let the charts show their own skeletons. */
+ isRefetching: boolean;
+ /** Whether the current (resolved) filters match any API keys — regardless of their usage. */
+ hasData: boolean;
+ /** Total number of calls matching the current filters — drives the events pagination. */
+ count: number;
+ /** Set when the count query itself failed (e.g. a 500) — the page should show an error, not spin forever. */
+ error: unknown;
+ /** The table lookup settled, but found no table to query at all (the audit db hasn't synced the
+ * view). The charts and tables below this page can't do anything with a null table either — they
+ * just sit on their own skeletons forever — so the caller should show the empty/error state
+ * instead of rendering them, regardless of `hasData`. */
+ tablesMissing: boolean;
+};
+
+/**
+ * Drives the page's load/empty/data states. "Has data" means at least one API key matches the
+ * current API key/user/group filters, or the filtered call count is nonzero — independent of
+ * whether a *matching* key currently has usage, so the Key activity table can still show a key
+ * with no activity instead of the page going empty, and a deleted key's history stays reachable
+ * (see `count > 0` below). Still runs the filtered total-count query, since the Events tab's
+ * pagination needs it. Distinguishes the initial load (loader) from a filter-change refetch
+ * (skeletons) so the page never flashes the empty state before the first result has resolved.
+ */
+export function useApiKeyUsageHasData({
+ provider,
+ table,
+ groupMembersTable,
+ isLoadingTables,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+}: DataSources & ApiKeyUsageFilters): Result {
+ const query = useMemo(
+ () =>
+ provider && table && groupMembersTable
+ ? buildTotalCountQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ })
+ : null,
+ [provider, table, groupMembersTable, dateFilter, apiKeyId, userId, groupId],
+ );
+
+ const { data, isFetching, error } = useAdhocBreakoutQuery(query);
+ const {
+ data: apiKeys,
+ isFetching: isFetchingKeys,
+ error: keysError,
+ } = useListApiKeysQuery();
+
+ // Latch once the first count resolves (successfully or not); from then on a fetch is a
+ // refetch, not initial load.
+ const hasLoadedOnce = useRef(false);
+ const combinedError = error ?? keysError;
+ const hasError = combinedError != null;
+ const resolved = isResolved({
+ isLoadingTables,
+ isFetching,
+ isFetchingKeys,
+ query,
+ data,
+ apiKeys,
+ hasError,
+ });
+ if (resolved) {
+ hasLoadedOnce.current = true;
+ }
+
+ // The query is a single count aggregation with no breakout, so the result is exactly one row
+ // with one column — the scalar total. `rows[0][0]` is that count.
+ const count = Number(data?.data?.rows?.[0]?.[0] ?? 0);
+ // `count > 0` keeps a deleted key's history reachable: once no live key matches the filters,
+ // nothing in `apiKeys` can match either, but the usage log rows (and the key's name on them)
+ // still exist and still match the filters' date range.
+ const hasData =
+ count > 0 ||
+ (apiKeys?.some((apiKey) =>
+ apiKeyMatchesScope(apiKey, { apiKeyId, userId, groupId }),
+ ) ??
+ false);
+
+ const tablesMissing =
+ !isLoadingTables &&
+ (provider == null || table == null || groupMembersTable == null);
+
+ return {
+ isInitialLoading: !hasLoadedOnce.current,
+ isRefetching: hasLoadedOnce.current && (isFetching || isFetchingKeys),
+ hasData,
+ count,
+ error: combinedError,
+ tablesMissing,
+ };
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageHasData.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageHasData.unit.spec.ts
new file mode 100644
index 00000000000..c6821c4d69f
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/hooks/useApiKeyUsageHasData.unit.spec.ts
@@ -0,0 +1,56 @@
+import { isResolved } from "./useApiKeyUsageHasData";
+
+const resolvedArgs = {
+ isLoadingTables: false,
+ isFetching: false,
+ isFetchingKeys: false,
+ query: {},
+ data: {},
+ apiKeys: [],
+ hasError: false,
+};
+
+describe("isResolved", () => {
+ it("is false while the table lookup is still loading, even with a query already built", () => {
+ expect(isResolved({ ...resolvedArgs, isLoadingTables: true })).toBe(false);
+ });
+
+ it("is true once the table lookup finishes but finds no table (query stays null) — the bug this guards against", () => {
+ expect(isResolved({ ...resolvedArgs, query: null, data: undefined })).toBe(
+ true,
+ );
+ });
+
+ it("is false if the table lookup finished with no table, but the keys list hasn't settled yet", () => {
+ expect(
+ isResolved({
+ ...resolvedArgs,
+ query: null,
+ data: undefined,
+ isFetchingKeys: true,
+ }),
+ ).toBe(false);
+ });
+
+ it("is false while the count query is still fetching, with a table found", () => {
+ expect(isResolved({ ...resolvedArgs, isFetching: true })).toBe(false);
+ });
+
+ it("is false while the count data hasn't arrived yet, with a table found", () => {
+ expect(isResolved({ ...resolvedArgs, data: undefined })).toBe(false);
+ });
+
+ it("is true once the count data arrives, with a table found", () => {
+ expect(isResolved(resolvedArgs)).toBe(true);
+ });
+
+ it("is true on an error, even with no count data", () => {
+ expect(
+ isResolved({ ...resolvedArgs, data: undefined, hasError: true }),
+ ).toBe(true);
+ });
+
+ it("is false until the keys list itself has loaded", () => {
+ expect(isResolved({ ...resolvedArgs, apiKeys: undefined })).toBe(false);
+ });
+});
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/index.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/index.ts
new file mode 100644
index 00000000000..bf79d6bc97a
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/index.ts
@@ -0,0 +1,16 @@
+import { PLUGIN_MONITOR } from "metabase/plugins";
+import { hasPremiumFeature } from "metabase-enterprise/settings";
+
+import { getApiKeyUsageRoutes } from "./routes";
+
+/**
+ * API key usage is gated on `audit_app` (the same token feature that gates the rest of the
+ * Monitor "Logs and activity" section), not on any AI-specific feature — this page is plain
+ * REST-API-call analytics and intentionally does not live under AI Auditing.
+ */
+export function initializePlugin() {
+ if (hasPremiumFeature("audit_app")) {
+ PLUGIN_MONITOR.isApiKeyUsageEnabled = true;
+ PLUGIN_MONITOR.getApiKeyUsageRoutes = getApiKeyUsageRoutes;
+ }
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/query-utils.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/query-utils.ts
new file mode 100644
index 00000000000..d265e386382
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/query-utils.ts
@@ -0,0 +1,367 @@
+import type { DateFilterValue } from "metabase/querying/common/types";
+import {
+ applyDateFilter,
+ applyIdFilter,
+ breakoutByColumn,
+ findColumn,
+ joinGroupMembers,
+} from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationStatsPage/query-utils";
+import type {
+ CardMetadata,
+ ColumnMetadata,
+ MetadataProvider,
+ Query,
+ TableMetadata,
+} from "metabase-lib";
+import * as Lib from "metabase-lib";
+import type { ApiKey, SortDirection } from "metabase-types/api";
+
+export type ApiKeyUsageFilters = {
+ dateFilter: DateFilterValue;
+ apiKeyId?: number;
+ userId?: number;
+ groupId?: number;
+};
+
+/**
+ * Whether `apiKey` matches the page's API key/user/group filters, by the key's own metadata
+ * (id/creator/group) rather than its usage. Shared by anything that needs to know which keys are
+ * in scope independent of whether they have any activity — e.g. the Key activity table, and the
+ * check for whether the page has anything to show at all.
+ */
+export function apiKeyMatchesScope(
+ apiKey: ApiKey,
+ {
+ apiKeyId,
+ userId,
+ groupId,
+ }: Pick<ApiKeyUsageFilters, "apiKeyId" | "userId" | "groupId">,
+): boolean {
+ return (
+ (apiKeyId == null || apiKey.id === apiKeyId) &&
+ (userId == null || apiKey.creator_id === userId) &&
+ (groupId == null || apiKey.group.id === groupId)
+ );
+}
+
+/**
+ * Whether `apiKey` is outside the Group filter's `groupId`. With no group set ("All groups"),
+ * every key is inside. Group and API key filter like State and City: the key list only offers the
+ * chosen group's keys, and picking a group the selected key isn't in clears the key. So the UI
+ * never produces an outside key itself — only a stale or hand-edited URL can.
+ */
+export function isKeyOutsideGroup(
+ apiKey: Pick<ApiKey, "group"> | undefined,
+ groupId: number | null | undefined,
+): boolean {
+ return apiKey != null && groupId != null && apiKey.group.id !== groupId;
+}
+
+type ApiKeyUsageDataSources = {
+ provider: MetadataProvider;
+ table: TableMetadata | CardMetadata;
+ groupMembersTable: TableMetadata | CardMetadata;
+};
+
+// Name of the count aggregation column produced by `Lib.aggregateByCount`.
+const COUNT_COLUMN = "count";
+
+/**
+ * Apply the shared API key/user/group filters to a query. The API key and user filters are plain
+ * equality checks on columns the view already has. The group filter means the key's own group —
+ * matching the Key activity table (which scopes by `apiKey.group.id`, the key's group from
+ * `GET /api/api-key`) — so it joins the audit `v_group_members` view on `actor_user_id`, not the
+ * creator: a key has exactly one group through its own user, while its creator may belong to
+ * several. Each no-ops when its id is unset.
+ */
+function applyScopeFilters(
+ query: Query,
+ {
+ apiKeyId,
+ userId,
+ groupId,
+ }: Pick<ApiKeyUsageFilters, "apiKeyId" | "userId" | "groupId">,
+ groupMembersTable: TableMetadata | CardMetadata,
+): Query {
+ query = applyIdFilter(query, "api_key_id", apiKeyId);
+ // `userId` here means the key's creator (the "Created by" filter) — the view's `creator_id`,
+ // not its `actor_user_id` (the key's own synthetic service-account user).
+ query = applyIdFilter(query, "creator_id", userId);
+ query =
+ groupId != null
+ ? joinGroupMembers(query, groupMembersTable, "actor_user_id")
+ : query;
+ query = groupId != null ? applyIdFilter(query, "group_id", groupId) : query;
+ return query;
+}
+
+/**
+ * The shared prelude every builder starts from: the view query with the date + scope
+ * (API key/user/group) filters applied. Centralizing it keeps the filter handling in one place so
+ * a builder can't silently drop a filter.
+ */
+function buildBaseQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+}: ApiKeyUsageFilters & ApiKeyUsageDataSources): Query {
+ let query = Lib.queryFromTableOrCardMetadata(provider, table);
+ query = applyDateFilter(query, dateFilter, "occurred_at");
+ query = applyScopeFilters(
+ query,
+ { apiKeyId, userId, groupId },
+ groupMembersTable,
+ );
+ return query;
+}
+
+/** Order an aggregated query by the count column descending (highest counts first). */
+function orderByCountDesc(query: Query): Query {
+ const countCol = findColumn(query, COUNT_COLUMN, Lib.orderableColumns);
+ return countCol ? Lib.orderBy(query, 0, countCol, "desc") : query;
+}
+
+/** Add an `occurred_at` breakout bucketed by day (falls back to the raw column if the day bucket is unavailable). */
+function breakoutByOccurredAtDay(query: Query): Query {
+ const col = findColumn(query, "occurred_at", Lib.breakoutableColumns);
+ if (!col) {
+ return query;
+ }
+ const dayBucket = Lib.availableTemporalBuckets(query, 0, col).find(
+ (bucket) => Lib.displayInfo(query, 0, bucket).shortName === "day",
+ );
+ const bucketed = dayBucket ? Lib.withTemporalBucket(col, dayBucket) : col;
+ return Lib.breakout(query, 0, bucketed);
+}
+
+type CountBreakoutQueryOpts = ApiKeyUsageFilters &
+ ApiKeyUsageDataSources & {
+ breakoutColumn: string;
+ };
+
+/**
+ * Build a "count of calls grouped by `breakoutColumn`" query (filtered + ordered by count desc).
+ * Used by the single-breakout charts — calls by client, by route, by user.
+ */
+export function buildCountBreakoutQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ breakoutColumn,
+}: CountBreakoutQueryOpts): Query {
+ let query = buildBaseQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ });
+ query = Lib.aggregateByCount(query, 0);
+ query = breakoutByColumn(query, breakoutColumn);
+ query = orderByCountDesc(query);
+ return query;
+}
+
+/**
+ * Build a "calls per day" query — a single-series time series of the total call count. Used by
+ * the "Calls over time" chart.
+ */
+export function buildCallsByDayQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+}: ApiKeyUsageFilters & ApiKeyUsageDataSources): Query {
+ let query = buildBaseQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ });
+ query = Lib.aggregateByCount(query, 0);
+ query = breakoutByOccurredAtDay(query);
+ return query;
+}
+
+/**
+ * Build a single-number count over the filtered view, used to decide whether the page has any
+ * data to show (so we can render one empty state instead of a grid of empty charts).
+ */
+export function buildTotalCountQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+}: ApiKeyUsageFilters & ApiKeyUsageDataSources): Query {
+ let query = buildBaseQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ });
+ query = Lib.aggregateByCount(query, 0);
+ return query;
+}
+
+/** Add a MAX(occurred_at) aggregation, mirroring the shared module's `addSumAggregation`. */
+function aggregateByMaxOccurredAt(query: Query): Query {
+ const operators = Lib.availableAggregationOperators(query, 0);
+ const maxOperator = operators.find(
+ (operator) => Lib.displayInfo(query, 0, operator).shortName === "max",
+ );
+ if (!maxOperator) {
+ return query;
+ }
+ const column = Lib.aggregationOperatorColumns(maxOperator).find(
+ (col) =>
+ Lib.displayInfo(query, 0, col).name?.toLowerCase() === "occurred_at",
+ );
+ return column
+ ? Lib.aggregate(query, 0, Lib.aggregationClause(maxOperator, column))
+ : query;
+}
+
+/**
+ * Build a "most recent activity per API key" query: one row per key with at least one call
+ * matching the current filters, breaking out by `api_key_id` and aggregating its latest
+ * `occurred_at`. Used to scope the Key activity table's rows — and its "Last used" column — to
+ * the same date/API key/user/group filters as the rest of the page.
+ */
+export function buildKeyActivityQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+}: ApiKeyUsageFilters & ApiKeyUsageDataSources): Query {
+ let query = buildBaseQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ });
+ query = breakoutByColumn(query, "api_key_id");
+ query = aggregateByMaxOccurredAt(query);
+ return query;
+}
+
+export const API_KEY_USAGE_EVENT_SORT_COLUMNS = [
+ "log_id",
+ "occurred_at",
+ "route_template",
+ "http_method",
+ "status",
+ "duration_ms",
+ "api_key_name",
+ "creator_display_name", // the key's creator, shown in the UI as "Created by"
+ "client_display_name",
+ "embedding_client",
+ "embedding_hostname",
+ "ip_address",
+] as const;
+
+export type ApiKeyUsageEventSortColumn =
+ (typeof API_KEY_USAGE_EVENT_SORT_COLUMNS)[number];
+
+// Columns in API_KEY_USAGE_EVENT_SORT_COLUMNS that only show up when PII retention is on.
+const PII_ONLY_COLUMNS: ApiKeyUsageEventSortColumn[] = ["ip_address"];
+
+export function apiKeyUsageEventColumnKeys(
+ hasPii: boolean,
+): ApiKeyUsageEventSortColumn[] {
+ return API_KEY_USAGE_EVENT_SORT_COLUMNS.filter(
+ (column) => hasPii || !PII_ONLY_COLUMNS.includes(column),
+ );
+}
+
+/** Append an order-by on `columnName` in `direction` if it's orderable. No-op if absent. */
+function orderByColumn(
+ query: Query,
+ columnName: string,
+ direction: "asc" | "desc",
+): Query {
+ const col = findColumn(query, columnName, Lib.orderableColumns);
+ return col ? Lib.orderBy(query, 0, col, direction) : query;
+}
+
+function projectToEventColumns(query: Query, hasPii: boolean): Query {
+ const fields = apiKeyUsageEventColumnKeys(hasPii)
+ .map((name) => findColumn(query, name, Lib.fieldableColumns))
+ .filter((column): column is ColumnMetadata => column != null);
+ return Lib.withFields(query, 0, fields);
+}
+
+type EventsQueryOpts = ApiKeyUsageFilters &
+ ApiKeyUsageDataSources & {
+ sortColumn?: ApiKeyUsageEventSortColumn;
+ sortDirection?: SortDirection;
+ hasPii: boolean;
+ };
+
+export function buildEventsQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ sortColumn = "occurred_at",
+ sortDirection = "desc",
+ hasPii,
+}: EventsQueryOpts): Query {
+ let query = buildBaseQuery({
+ provider,
+ table,
+ groupMembersTable,
+ dateFilter,
+ apiKeyId,
+ userId,
+ groupId,
+ });
+
+ query = orderByColumn(query, sortColumn, sortDirection);
+ query = orderByColumn(query, "log_id", "desc");
+ query = projectToEventColumns(query, hasPii);
+
+ return query;
+}
+
+/**
+ * Restrict the events query to a single page via the MBQL `:page` clause. `page` is 0-indexed
+ * here; metabase-lib's `:page` is 1-indexed, so we add 1.
+ */
+export function paginateEventsQuery(
+ query: Query,
+ page: number,
+ pageSize: number,
+): Query {
+ return Lib.withPage(query, 0, { page: page + 1, items: pageSize });
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/query-utils.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/query-utils.unit.spec.ts
new file mode 100644
index 00000000000..4d33e4ec5fc
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/query-utils.unit.spec.ts
@@ -0,0 +1,98 @@
+import type { ApiKey } from "metabase-types/api";
+
+import {
+ apiKeyMatchesScope,
+ apiKeyUsageEventColumnKeys,
+ isKeyOutsideGroup,
+} from "./query-utils";
+
+const apiKey: ApiKey = {
+ id: 1,
+ name: "Test key",
+ group: { id: 2, name: "Administrators" },
+ creator_id: 3,
+ masked_key: "mb_************abcd",
+ created_at: "2026-01-01T00:00:00Z",
+ updated_at: "2026-01-01T00:00:00Z",
+ updated_by: { id: 3, common_name: "Admin" },
+ last_used_at: null,
+};
+
+describe("apiKeyMatchesScope", () => {
+ it("matches when no filters are set", () => {
+ expect(apiKeyMatchesScope(apiKey, {})).toBe(true);
+ });
+
+ it("matches on api key id", () => {
+ expect(apiKeyMatchesScope(apiKey, { apiKeyId: 1 })).toBe(true);
+ expect(apiKeyMatchesScope(apiKey, { apiKeyId: 99 })).toBe(false);
+ });
+
+ it("matches on creator id", () => {
+ expect(apiKeyMatchesScope(apiKey, { userId: 3 })).toBe(true);
+ expect(apiKeyMatchesScope(apiKey, { userId: 99 })).toBe(false);
+ });
+
+ it("matches on group id", () => {
+ expect(apiKeyMatchesScope(apiKey, { groupId: 2 })).toBe(true);
+ expect(apiKeyMatchesScope(apiKey, { groupId: 99 })).toBe(false);
+ });
+
+ it("requires every set filter to match", () => {
+ expect(apiKeyMatchesScope(apiKey, { apiKeyId: 1, userId: 99 })).toBe(false);
+ });
+});
+
+describe("isKeyOutsideGroup", () => {
+ it("is false when no key is selected", () => {
+ expect(isKeyOutsideGroup(undefined, 5)).toBe(false);
+ });
+
+ it("is false when the group is the key's own group", () => {
+ expect(isKeyOutsideGroup(apiKey, 2)).toBe(false);
+ });
+
+ it("is false with no group set (All groups)", () => {
+ expect(isKeyOutsideGroup(apiKey, null)).toBe(false);
+ expect(isKeyOutsideGroup(apiKey, undefined)).toBe(false);
+ });
+
+ it("is true when the group isn't the key's own group", () => {
+ expect(isKeyOutsideGroup(apiKey, 5)).toBe(true);
+ });
+});
+
+describe("apiKeyUsageEventColumnKeys", () => {
+ it("returns only the base columns when PII retention is off", () => {
+ expect(apiKeyUsageEventColumnKeys(false)).toEqual([
+ "log_id",
+ "occurred_at",
+ "route_template",
+ "http_method",
+ "status",
+ "duration_ms",
+ "api_key_name",
+ "creator_display_name",
+ "client_display_name",
+ "embedding_client",
+ "embedding_hostname",
+ ]);
+ });
+
+ it("includes ip_address only when PII retention is on", () => {
+ expect(apiKeyUsageEventColumnKeys(true)).toEqual([
+ "log_id",
+ "occurred_at",
+ "route_template",
+ "http_method",
+ "status",
+ "duration_ms",
+ "api_key_name",
+ "creator_display_name",
+ "client_display_name",
+ "embedding_client",
+ "embedding_hostname",
+ "ip_address",
+ ]);
+ });
+});
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/raw-series.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/raw-series.ts
new file mode 100644
index 00000000000..adbc4700bdb
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/raw-series.ts
@@ -0,0 +1,106 @@
+import type { ColorName } from "metabase/ui/colors/types";
+import type { DatasetQuery, VisualizationDisplay } from "metabase-types/api";
+
+type GetColor = (name: ColorName) => string;
+
+type RawDataCol = { source?: string; name?: string };
+type RawData = { cols: RawDataCol[]; rows: unknown[][] };
+type AdhocResponse = { data?: RawData } | undefined;
+
+type Opts = {
+ display: VisualizationDisplay;
+ maxCategories?: number;
+ otherLabel: string;
+ getColor: GetColor;
+};
+
+/**
+ * Keep the top `max - 1` rows (already count-ordered) and fold the remaining long tail into a
+ * single "Other" row whose metric is the summed overflow. Returns rows unchanged when there's
+ * nothing to collapse (in particular, when `max` is unset — used for the day breakout, which
+ * should never be collapsed).
+ */
+function collapseToTopN(
+ rows: unknown[][],
+ dimensionIndex: number,
+ metricIndex: number,
+ max: number | undefined,
+ otherLabel: string,
+ colCount: number,
+): unknown[][] {
+ const shouldCollapse =
+ max != null && dimensionIndex >= 0 && metricIndex >= 0 && rows.length > max;
+ if (!shouldCollapse) {
+ return rows;
+ }
+ const keep = rows.slice(0, max - 1);
+ const overflow = rows.slice(max - 1);
+ const otherRow: unknown[] = new Array(colCount).fill(null);
+ otherRow[dimensionIndex] = otherLabel;
+ otherRow[metricIndex] = overflow.reduce(
+ (sum, row) => sum + (Number(row[metricIndex]) || 0),
+ 0,
+ );
+ return [...keep, otherRow];
+}
+
+/**
+ * Build a single-breakout rawSeries (one dimension + the count metric) for `bar`/`row`/`pie`/`line`
+ * displays. Long tails are collapsed into a single "Other" category when `maxCategories` is set.
+ */
+export function toCountBreakoutRawSeries(
+ response: AdhocResponse,
+ jsQuery: DatasetQuery | null,
+ opts: Opts,
+) {
+ if (!response?.data || !jsQuery) {
+ return null;
+ }
+
+ const { display, maxCategories, otherLabel, getColor } = opts;
+ const cols = response.data.cols;
+ const dimensionIndex = cols.findIndex((c) => c.source === "breakout");
+ const metricIndex = cols.findIndex((c) => c.source === "aggregation");
+ const dimensionName =
+ dimensionIndex >= 0 ? cols[dimensionIndex].name : undefined;
+ const countColumnName =
+ metricIndex >= 0 ? (cols[metricIndex].name ?? "count") : "count";
+
+ const visualizationSettings =
+ display === "pie"
+ ? {
+ "pie.dimension": dimensionName,
+ "pie.metric": countColumnName,
+ }
+ : {
+ "graph.x_axis.title_text": "",
+ "graph.y_axis.title_text": "",
+ ...(display === "bar" && {
+ "graph.x_axis.axis_enabled": "compact" as const,
+ }),
+ series_settings: {
+ [countColumnName]: { color: getColor("accent0") },
+ },
+ };
+
+ return [
+ {
+ card: {
+ display,
+ dataset_query: jsQuery,
+ visualization_settings: visualizationSettings,
+ },
+ data: {
+ ...response.data,
+ rows: collapseToTopN(
+ response.data.rows,
+ dimensionIndex,
+ metricIndex,
+ maxCategories,
+ otherLabel,
+ cols.length,
+ ),
+ },
+ },
+ ];
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/raw-series.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/raw-series.unit.spec.ts
new file mode 100644
index 00000000000..4eaec80f391
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/raw-series.unit.spec.ts
@@ -0,0 +1,81 @@
+import type { StructuredDatasetQuery } from "metabase-types/api";
+
+import { toCountBreakoutRawSeries } from "./raw-series";
+
+const jsQuery: StructuredDatasetQuery = {
+ database: 1,
+ type: "query",
+ query: {},
+};
+
+const opts = {
+ display: "row" as const,
+ otherLabel: "Other",
+ getColor: () => "#509EE3",
+};
+
+/** A single-breakout count response: one `breakout` dimension col + one `aggregation` metric col. */
+const response = (rows: unknown[][]) => ({
+ data: {
+ cols: [
+ { source: "breakout", name: "client_display_name" },
+ { source: "aggregation", name: "count" },
+ ],
+ rows,
+ },
+});
+
+const rowsOf = (series: ReturnType<typeof toCountBreakoutRawSeries>) =>
+ series?.[0].data.rows;
+
+describe("toCountBreakoutRawSeries collapse behavior", () => {
+ it("folds the long tail into a single summed 'Other' row when rows exceed maxCategories", () => {
+ const series = toCountBreakoutRawSeries(
+ response([
+ ["A", 10],
+ ["B", 7],
+ ["C", 5],
+ ["D", 3],
+ ["E", 1],
+ ]),
+ jsQuery,
+ { ...opts, maxCategories: 3 },
+ );
+
+ // keep top (max - 1) = 2, fold the remaining 3 into "Other" summing 5 + 3 + 1 = 9
+ expect(rowsOf(series)).toEqual([
+ ["A", 10],
+ ["B", 7],
+ ["Other", 9],
+ ]);
+ });
+
+ it("leaves rows untouched when the count is within maxCategories", () => {
+ const rows = [
+ ["A", 10],
+ ["B", 7],
+ ];
+ const series = toCountBreakoutRawSeries(response(rows), jsQuery, {
+ ...opts,
+ maxCategories: 3,
+ });
+ expect(rowsOf(series)).toEqual(rows);
+ });
+
+ it("leaves rows untouched when maxCategories is unset (e.g. the day-breakout timeline chart)", () => {
+ const rows = [
+ ["2026-01-01", 10],
+ ["2026-01-02", 7],
+ ["2026-01-03", 5],
+ ];
+ const series = toCountBreakoutRawSeries(response(rows), jsQuery, opts);
+ expect(rowsOf(series)).toEqual(rows);
+ });
+
+ it("returns null without data or query", () => {
+ expect(toCountBreakoutRawSeries(undefined, jsQuery, opts)).toBeNull();
+ expect(
+ toCountBreakoutRawSeries(response([["A", 1]]), null, opts),
+ ).toBeNull();
+ });
+});
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/routes.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/routes.tsx
new file mode 100644
index 00000000000..2fa86194d87
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/routes.tsx
@@ -0,0 +1,41 @@
+import { Route, redirect, registerPagePrefetch } from "metabase/router";
+import * as Urls from "metabase/urls";
+
+/**
+ * The API key usage pages sit behind one barrel, so a single `import()` reaches all three and
+ * they land in one chunk by construction — no risk of the webpackChunkName comments drifting
+ * apart and silently splitting the bundle.
+ */
+const pages = () =>
+ import(/* webpackChunkName: "api-key-usage" */ "./components");
+
+const apiKeyUsageSectionLayout = () =>
+ pages().then(({ ApiKeyUsageSectionLayout }) => ({
+ Component: ApiKeyUsageSectionLayout,
+ }));
+
+const apiKeyUsagePage = () =>
+ pages().then(({ ApiKeyUsagePage }) => ({ Component: ApiKeyUsagePage }));
+
+const apiKeyUsageEventsPage = () =>
+ pages().then(({ ApiKeyUsageEventsPage }) => ({
+ Component: ApiKeyUsageEventsPage,
+ }));
+
+/**
+ * Hovering the Monitor sidebar link starts the fetch, so the chunk is usually in hand by the
+ * time the click lands.
+ */
+registerPagePrefetch(Urls.monitorApiKeyUsage(), apiKeyUsageSectionLayout);
+
+export function getApiKeyUsageRoutes() {
+ return (
+ <>
+ <Route index element={redirect("usage")} />
+ <Route lazy={apiKeyUsageSectionLayout}>
+ <Route path="usage" lazy={apiKeyUsagePage} />
+ <Route path="events" lazy={apiKeyUsageEventsPage} />
+ </Route>
+ </>
+ );
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/url-state.ts b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/url-state.ts
new file mode 100644
index 00000000000..cd77b5e03f9
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/monitor/api-key-usage/url-state.ts
@@ -0,0 +1,76 @@
+import {
+ type QueryParam,
+ type UrlStateConfig,
+ getFirstParamValue,
+ parsePage,
+ parseSortColumn,
+ parseSortDirection,
+} from "metabase/common/hooks/use-url-state";
+import {
+ type FilterUrlState,
+ filterUrlStateConfig,
+ mergeUrlStateConfig,
+} from "metabase-enterprise/monitor/ai-auditing/metabot-analytics/components/ConversationFilters/url-state";
+import type { SortDirection } from "metabase-types/api";
+
+import {
+ API_KEY_USAGE_EVENT_SORT_COLUMNS,
+ type ApiKeyUsageEventSortColumn,
+} from "./query-utils";
+
+type ApiKeyUsageEventsUrlState = {
+ /** The API key an admin is scoping the page to — not part of the shared filter bar, so it's
+ * tracked here rather than in `FilterUrlState`. */
+ api_key: string | null;
+ /** Current page of the row-level events table, 0-indexed. */
+ page: number;
+ sort_column: ApiKeyUsageEventSortColumn;
+ sort_direction: SortDirection;
+};
+
+export type ApiKeyUsageUrlState = FilterUrlState & ApiKeyUsageEventsUrlState;
+
+const DEFAULT_SORT_COLUMN: ApiKeyUsageEventSortColumn = "occurred_at";
+const DEFAULT_SORT_DIRECTION: SortDirection = "desc";
+
+function parseApiKey(param: QueryParam): string | null {
+ const value = getFirstParamValue(param);
+ return value && value.trim().length > 0 ? value.trim() : null;
+}
+
+const apiKeyUsageEventsUrlStateConfig: UrlStateConfig<ApiKeyUsageEventsUrlState> =
+ {
+ parse: (query) => ({
+ api_key: parseApiKey(query.api_key),
+ page: parsePage(query.page),
+ sort_column: parseSortColumn(
+ query.sort_column,
+ API_KEY_USAGE_EVENT_SORT_COLUMNS,
+ DEFAULT_SORT_COLUMN,
+ ),
+ sort_direction: parseSortDirection(
+ query.sort_direction,
+ DEFAULT_SORT_DIRECTION,
+ ),
+ }),
+ serialize: ({ api_key, page, sort_column, sort_direction }) => ({
+ api_key: api_key ?? undefined,
+ page: page === 0 ? undefined : String(page),
+ sort_column:
+ sort_column === DEFAULT_SORT_COLUMN ? undefined : sort_column,
+ sort_direction:
+ sort_direction === DEFAULT_SORT_DIRECTION ? undefined : sort_direction,
+ }),
+ };
+
+const mergedUrlStateConfig = mergeUrlStateConfig(
+ filterUrlStateConfig,
+ apiKeyUsageEventsUrlStateConfig,
+);
+
+export const apiKeyUsageUrlStateConfig: UrlStateConfig<ApiKeyUsageUrlState> = {
+ ...mergedUrlStateConfig,
+ // This page has no user/creator filter concept — "Created by" is just a column now — so a
+ // stray `?user=` query param must not silently scope every query.
+ parse: (query) => ({ ...mergedUrlStateConfig.parse(query), user: null }),
+};
diff --git a/enterprise/frontend/src/metabase-enterprise/plugins.ts b/enterprise/frontend/src/metabase-enterprise/plugins.ts
index 4b322364e4e..d165f26bcc8 100644
--- a/enterprise/frontend/src/metabase-enterprise/plugins.ts
+++ b/enterprise/frontend/src/metabase-enterprise/plugins.ts
@@ -32,6 +32,7 @@ import { initializePlugin as initializeGroupManagers } from "./group_managers";
import { initializePlugin as initializeMetabot } from "./metabot";
import { initializePlugin as initializeModelPersistence } from "./model_persistence";
import { initializePlugin as initializeModeration } from "./moderation";
+import { initializePlugin as initializeMonitorApiKeyUsage } from "./monitor/api-key-usage";
import { initializePlugin as initializeMonitorDependencyDiagnostics } from "./monitor/dependency-diagnostics";
import { initializePlugin as initializeMonitorSessionManagement } from "./monitor/session-management";
import { initializePlugin as initializeTools } from "./monitor/tools";
@@ -88,6 +89,7 @@ export function initializePlugins() {
initializeMetabot();
initializeModelPersistence();
initializeModeration();
+ initializeMonitorApiKeyUsage();
initializeMonitorDependencyDiagnostics();
initializeMonitorSessionManagement();
initializeMultiFactorAuth();
diff --git a/frontend/src/metabase-types/analytics/event.ts b/frontend/src/metabase-types/analytics/event.ts
index dc84fa74312..6357c9c3053 100644
--- a/frontend/src/metabase-types/analytics/event.ts
+++ b/frontend/src/metabase-types/analytics/event.ts
@@ -76,25 +76,3 @@ export type InviteToViewOpenedEvent = ValidateEvent<{
triggered_from: "dashboard" | "question";
target_id: number | null;
}>;
-
-export type MonitorOpenedEvent = ValidateEvent<{
- event: "monitor_opened";
- triggered_from: "nav_menu";
-}>;
-
-export type MonitorSectionClickedEvent = ValidateEvent<{
- event: "monitor_section_clicked";
- event_detail:
- | "diagnostics"
- | "erroring-questions"
- | "alerts"
- | "tasks"
- | "jobs"
- | "logs"
- | "model-caching"
- | "session-management"
- | "ai-auditing-usage-stats"
- | "ai-auditing-conversations"
- | "ai-auditing-mcp"
- | "ai-auditing-cli";
-}>;
diff --git a/frontend/src/metabase-types/api/admin.ts b/frontend/src/metabase-types/api/admin.ts
index 5f9b5203ee4..ecc968c506a 100644
--- a/frontend/src/metabase-types/api/admin.ts
+++ b/frontend/src/metabase-types/api/admin.ts
@@ -15,6 +15,8 @@ export type ApiKey = {
id: number;
common_name: string;
};
+ /** Throttled liveness timestamp, stamped on each authenticated request. Null until first use. */
+ last_used_at?: string | null;
};
export type CreateApiKeyRequest = {
diff --git a/frontend/src/metabase/admin/settings/components/ApiKeys/ManageApiKeys.tsx b/frontend/src/metabase/admin/settings/components/ApiKeys/ManageApiKeys.tsx
index 81e5b059af5..6b57f2f2d4d 100644
--- a/frontend/src/metabase/admin/settings/components/ApiKeys/ManageApiKeys.tsx
+++ b/frontend/src/metabase/admin/settings/components/ApiKeys/ManageApiKeys.tsx
@@ -3,6 +3,7 @@ import { useCallback, useMemo, useState } from "react";
import { t } from "ttag";
import ApiKeysEmptyIllustration from "assets/img/api-keys-empty.svg?component";
+import { ForwardRefLink } from "metabase/common/components/Link";
import { DelayedLoadingAndErrorWrapper } from "metabase/common/components/LoadingAndErrorWrapper/DelayedLoadingAndErrorWrapper";
import { SettingsPageWrapper } from "metabase/settings-components";
import {
@@ -22,6 +23,7 @@ import {
type TreeTableColumnDef,
useTreeTableInstance,
} from "metabase/ui";
+import * as Urls from "metabase/urls";
import { formatDateTimeWithUnit } from "metabase/value-formatting";
import type { ApiKey } from "metabase-types/api";
@@ -260,9 +262,19 @@ export const ManageApiKeys = () => {
{t`Create API keys to let users authenticate API calls or make them programmatically.`}
</Text>
</Box>
- <Button variant="filled" onClick={() => setModal("create")}>
- {t`Create an API key`}
- </Button>
+ <Group gap="sm">
+ <Button
+ variant="subtle"
+ component={ForwardRefLink}
+ to={Urls.monitorApiKeyUsage()}
+ leftSection={<Icon name="key" />}
+ >
+ {t`View API key usage`}
+ </Button>
+ <Button variant="filled" onClick={() => setModal("create")}>
+ {t`Create an API key`}
+ </Button>
+ </Group>
</Group>
<Card withBorder radius="sm" p={0} style={{ overflow: "hidden" }}>
{showLoadingOrError ? (
diff --git a/frontend/src/metabase/common/monitor/analytics.ts b/frontend/src/metabase/common/monitor/analytics.ts
index bfbb918f444..07b7436c364 100644
--- a/frontend/src/metabase/common/monitor/analytics.ts
+++ b/frontend/src/metabase/common/monitor/analytics.ts
@@ -1,21 +1,30 @@
import { trackSimpleEvent } from "metabase/analytics";
-import type {
- MonitorOpenedEvent,
- MonitorSectionClickedEvent,
-} from "metabase-types/analytics/event";
-export type MonitorSection = MonitorSectionClickedEvent["event_detail"];
+export type MonitorSection =
+ | "diagnostics"
+ | "erroring-questions"
+ | "alerts"
+ | "tasks"
+ | "jobs"
+ | "logs"
+ | "model-caching"
+ | "session-management"
+ | "ai-auditing-usage-stats"
+ | "ai-auditing-conversations"
+ | "ai-auditing-mcp"
+ | "ai-auditing-cli"
+ | "api-key-usage";
export const trackMonitorOpened = () => {
trackSimpleEvent({
event: "monitor_opened",
triggered_from: "nav_menu",
- } satisfies MonitorOpenedEvent);
+ });
};
export const trackMonitorSectionClicked = (section: MonitorSection) => {
trackSimpleEvent({
event: "monitor_section_clicked",
event_detail: section,
- } satisfies MonitorSectionClickedEvent);
+ });
};
diff --git a/frontend/src/metabase/common/monitor/selectors.ts b/frontend/src/metabase/common/monitor/selectors.ts
index 74068fe9668..5f45e9d8e82 100644
--- a/frontend/src/metabase/common/monitor/selectors.ts
+++ b/frontend/src/metabase/common/monitor/selectors.ts
@@ -46,6 +46,15 @@ export function canAccessAiAuditing(state: State) {
return getUserIsAdmin(state);
}
+// Admin-only, unlike the rest of Monitoring tools: the page loads `GET /api/api-key`, which is
+// superuser-only, so a non-admin with just the monitoring application permission would hit a 403.
+export function canAccessApiKeyUsage(state: State) {
+ if (isWithinIframe()) {
+ return false;
+ }
+ return getUserIsAdmin(state);
+}
+
export function canAccessMonitor(state: State) {
return (
canAccessMonitorDiagnostics(state) ||
diff --git a/frontend/src/metabase/common/monitor/selectors.unit.spec.ts b/frontend/src/metabase/common/monitor/selectors.unit.spec.ts
index 974338a1691..4d3722e78ae 100644
--- a/frontend/src/metabase/common/monitor/selectors.unit.spec.ts
+++ b/frontend/src/metabase/common/monitor/selectors.unit.spec.ts
@@ -8,6 +8,7 @@ import {
import {
canAccessAiAuditing,
canAccessAlertsManagement,
+ canAccessApiKeyUsage,
canAccessMonitor,
canAccessMonitorDiagnostics,
canAccessMonitoringTools,
@@ -326,3 +327,49 @@ describe("canAccessAiAuditing", () => {
expect(canAccessAiAuditing(state)).toBe(false);
});
});
+
+describe("canAccessApiKeyUsage", () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ isWithinIframe.mockReturnValue(false);
+ });
+
+ it("returns false when in embedding iframe", () => {
+ isWithinIframe.mockReturnValue(true);
+ const state = createMockState({
+ currentUser: createMockUser({ is_superuser: true }),
+ });
+
+ expect(canAccessApiKeyUsage(state)).toBe(false);
+ });
+
+ it("returns true when user is admin", () => {
+ const state = createMockState({
+ currentUser: createMockUser({ is_superuser: true }),
+ });
+
+ expect(canAccessApiKeyUsage(state)).toBe(true);
+ });
+
+ it("returns false for an analyst without admin", () => {
+ const state = createMockState({
+ currentUser: createMockUser({
+ is_superuser: false,
+ is_data_analyst: true,
+ }),
+ });
+
+ expect(canAccessApiKeyUsage(state)).toBe(false);
+ });
+
+ it("returns false for a non-admin with the monitoring application permission", () => {
+ const state = createMockState({
+ currentUser: createMockUser({
+ is_superuser: false,
+ permissions: { can_access_monitoring: true },
+ }),
+ });
+
+ expect(canAccessApiKeyUsage(state)).toBe(false);
+ });
+});
diff --git a/frontend/src/metabase/monitor/api-key-usage/ApiKeyUsageUpsellPage.tsx b/frontend/src/metabase/monitor/api-key-usage/ApiKeyUsageUpsellPage.tsx
new file mode 100644
index 00000000000..3e367f01c19
--- /dev/null
+++ b/frontend/src/metabase/monitor/api-key-usage/ApiKeyUsageUpsellPage.tsx
@@ -0,0 +1,19 @@
+import { t } from "ttag";
+
+import { usePageTitle } from "metabase/hooks/use-page-title";
+import { BaseUpsellPage } from "metabase/monitor/upsells";
+
+export function ApiKeyUsageUpsellPage() {
+ usePageTitle(t`API key usage`);
+
+ return (
+ <BaseUpsellPage
+ campaign="monitor-api-key-usage"
+ location="monitor-api-key-usage-page"
+ header={t`API key usage`}
+ title={t`See who's calling your API`}
+ description={t`Track which API keys are active, who's using them, and which routes and clients they're calling — so you can spot stale keys and unexpected usage.`}
+ image="app/assets/img/upsell-api-usage-analytics.png"
+ />
+ );
+}
diff --git a/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.tsx b/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.tsx
index 616d0bc0429..6a12d67c674 100644
--- a/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.tsx
+++ b/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.tsx
@@ -9,6 +9,7 @@ import {
import {
canAccessAiAuditing,
canAccessAlertsManagement,
+ canAccessApiKeyUsage,
canAccessMonitorDiagnostics,
canAccessMonitoringTools,
canAccessSessionManagement,
@@ -26,9 +27,11 @@ import * as Urls from "metabase/urls";
import { MonitorContent } from "./MonitorContent";
-function getActiveSection(pathname: string): MonitorSection | null {
+type ActiveSection = MonitorSection | null;
+
+function getActiveSection(pathname: string): ActiveSection {
return match(pathname)
- .returnType<MonitorSection | null>()
+ .returnType<ActiveSection>()
.with(
P.string.startsWith(Urls.dependencyDiagnostics()),
() => "diagnostics",
@@ -45,6 +48,7 @@ function getActiveSection(pathname: string): MonitorSection | null {
P.string.startsWith(Urls.monitorModelPersistenceLog()),
() => "model-caching",
)
+ .with(P.string.startsWith(Urls.monitorApiKeyUsage()), () => "api-key-usage")
.with(
P.string.startsWith(Urls.monitorSessions()),
() => "session-management",
@@ -89,6 +93,7 @@ export function MonitorLayout() {
const canAccessAlerts = useSelector(canAccessAlertsManagement);
const canAccessSessions = useSelector(canAccessSessionManagement);
const canAccessAiAuditingTab = useSelector(canAccessAiAuditing);
+ const canAccessApiKeyUsageTab = useSelector(canAccessApiKeyUsage);
const activeSection = getActiveSection(pathname);
@@ -187,6 +192,17 @@ export function MonitorLayout() {
onClick={() => trackMonitorSectionClicked("session-management")}
/>
)}
+ {canAccessApiKeyUsageTab && (
+ <AreaTab
+ label={t`API key usage`}
+ icon="key"
+ to={Urls.monitorApiKeyUsage()}
+ isSelected={activeSection === "api-key-usage"}
+ showLabel={isNavbarOpened}
+ isGated={!hasAuditAppFeature}
+ onClick={() => trackMonitorSectionClicked("api-key-usage")}
+ />
+ )}
</AreaTabGroup>
)}
{canAccessAiAuditingTab && hasAuditAppFeature && (
diff --git a/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.unit.spec.tsx b/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.unit.spec.tsx
index de3e69b5b0b..129e72d3770 100644
--- a/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.unit.spec.tsx
+++ b/frontend/src/metabase/monitor/components/MonitorLayout/MonitorLayout.unit.spec.tsx
@@ -153,6 +153,7 @@ describe("MonitorLayout", () => {
["Application logs", Urls.monitorLogs()],
["Model persistence log", Urls.monitorModelPersistenceLog()],
["Session management", Urls.monitorSessions()],
+ ["API key usage", Urls.monitorApiKeyUsage()],
];
expectedTabs.forEach(([name, href]) => {
@@ -201,6 +202,11 @@ describe("MonitorLayout", () => {
route: Urls.monitorSessions(),
section: "session-management",
},
+ {
+ label: "API key usage",
+ route: Urls.monitorApiKeyUsage(),
+ section: "api-key-usage",
+ },
] as const;
it.each(SECTION_CASES)(
@@ -326,7 +332,7 @@ describe("MonitorLayout", () => {
});
});
- it("hides Dependency diagnostics for a monitoring-only user, and hides Alerts management (admin-only)", async () => {
+ it("hides Dependency diagnostics for a monitoring-only user, and hides Alerts management and API key usage (admin-only)", async () => {
setup({
user: createMockUser({
is_superuser: false,
@@ -353,6 +359,10 @@ describe("MonitorLayout", () => {
expect(
screen.queryByRole("link", { name: "Alerts management" }),
).not.toBeInTheDocument();
+ // the page loads GET /api/api-key, which is superuser-only
+ expect(
+ screen.queryByRole("link", { name: "API key usage" }),
+ ).not.toBeInTheDocument();
});
it("hides Alerts management for an analyst even with the monitoring permission", async () => {
diff --git a/frontend/src/metabase/monitor/route-guards.tsx b/frontend/src/metabase/monitor/route-guards.tsx
index bfee9a50c9e..a25f30dff9b 100644
--- a/frontend/src/metabase/monitor/route-guards.tsx
+++ b/frontend/src/metabase/monitor/route-guards.tsx
@@ -1,6 +1,7 @@
import {
canAccessAiAuditing,
canAccessAlertsManagement,
+ canAccessApiKeyUsage,
canAccessMonitor,
canAccessMonitorDiagnostics,
canAccessMonitoringTools,
@@ -43,6 +44,11 @@ const UserCanAccessAiAuditing = createRedirectGuard(
"/unauthorized",
);
+const UserCanAccessApiKeyUsage = createRedirectGuard(
+ (state) => canAccessApiKeyUsage(state),
+ "/unauthorized",
+);
+
export const CanAccessMonitor = () => (
<MetabaseIsSetup>
<UserIsAuthenticated>
@@ -82,3 +88,9 @@ export const CanAccessAiAuditing = () => (
<Outlet />
</UserCanAccessAiAuditing>
);
+
+export const CanAccessApiKeyUsage = () => (
+ <UserCanAccessApiKeyUsage>
+ <Outlet />
+ </UserCanAccessApiKeyUsage>
+);
diff --git a/frontend/src/metabase/monitor/route-guards.unit.spec.tsx b/frontend/src/metabase/monitor/route-guards.unit.spec.tsx
index a51f8fe4720..543bda189d9 100644
--- a/frontend/src/metabase/monitor/route-guards.unit.spec.tsx
+++ b/frontend/src/metabase/monitor/route-guards.unit.spec.tsx
@@ -11,6 +11,7 @@ import {
import {
CanAccessAiAuditing,
CanAccessAlertsManagement,
+ CanAccessApiKeyUsage,
CanAccessMonitor,
} from "./route-guards";
@@ -230,4 +231,71 @@ describe("monitor route-guards", () => {
expect(screen.queryByText("ai auditing page")).not.toBeInTheDocument();
});
});
+
+ describe("CanAccessApiKeyUsage", () => {
+ interface SetupOpts {
+ currentUser?: ReturnType<typeof createMockUser>;
+ }
+
+ const setup = ({ currentUser }: SetupOpts = {}) => {
+ return renderWithProviders(
+ <>
+ <Route element={<CanAccessApiKeyUsage />}>
+ <Route
+ path="/monitor/api-key-usage"
+ element={<div>api key usage page</div>}
+ />
+ </Route>
+ <Route path="/unauthorized" element={<div>unauthorized</div>} />
+ </>,
+ {
+ storeInitialState: createMockState({
+ currentUser,
+ settings: createMockSettingsState({ "has-user-setup": true }),
+ }),
+ withRouter: true,
+ initialRoute: "/monitor/api-key-usage",
+ },
+ );
+ };
+
+ it("renders the page for superusers", async () => {
+ setup({ currentUser: createMockUser({ is_superuser: true }) });
+
+ expect(await screen.findByText("api key usage page")).toBeInTheDocument();
+ });
+
+ it("redirects a non-admin with monitoring permission to unauthorized without redirect-back", async () => {
+ const { router } = setup({
+ currentUser: createMockUser({
+ is_superuser: false,
+ is_data_analyst: false,
+ permissions: { can_access_monitoring: true },
+ }),
+ });
+
+ await waitFor(() => {
+ expect(router?.location.pathname).toBe("/unauthorized");
+ });
+
+ expect(parseSearchQuery(router?.location.search ?? "")).toEqual({});
+ expect(screen.queryByText("api key usage page")).not.toBeInTheDocument();
+ });
+
+ it("redirects an analyst to unauthorized without redirect-back", async () => {
+ const { router } = setup({
+ currentUser: createMockUser({
+ is_superuser: false,
+ is_data_analyst: true,
+ }),
+ });
+
+ await waitFor(() => {
+ expect(router?.location.pathname).toBe("/unauthorized");
+ });
+
+ expect(parseSearchQuery(router?.location.search ?? "")).toEqual({});
+ expect(screen.queryByText("api key usage page")).not.toBeInTheDocument();
+ });
+ });
});
diff --git a/frontend/src/metabase/monitor/routes.tsx b/frontend/src/metabase/monitor/routes.tsx
index fcb9e2b167c..265d7eb115c 100644
--- a/frontend/src/metabase/monitor/routes.tsx
+++ b/frontend/src/metabase/monitor/routes.tsx
@@ -29,6 +29,7 @@ import * as Urls from "metabase/urls";
import {
CanAccessAiAuditing,
CanAccessAlertsManagement,
+ CanAccessApiKeyUsage,
CanAccessMonitor,
CanAccessMonitorDiagnostics,
CanAccessMonitoringTools,
@@ -67,6 +68,13 @@ const dependencyDiagnosticsUpsellPage = () =>
Component: DependencyDiagnosticsUpsellPage,
}));
+const apiKeyUsageUpsellPage = () =>
+ import(
+ /* webpackChunkName: "monitor" */ "metabase/monitor/api-key-usage/ApiKeyUsageUpsellPage"
+ ).then(({ ApiKeyUsageUpsellPage }) => ({
+ Component: ApiKeyUsageUpsellPage,
+ }));
+
const jobInfoApp = () =>
import(
/* webpackChunkName: "monitor" */ "metabase/monitor/tools/components/JobInfoApp"
@@ -146,6 +154,22 @@ export function getMonitorRoutes() {
</Route>
</Route>
+ {/* Admin-only, unlike the rest of Monitoring tools above — the page loads
+ `GET /api/api-key`, superuser-only, so a non-admin with just the monitoring
+ application permission would hit a 403. */}
+ <Route element={<CanAccessApiKeyUsage />}>
+ {PLUGIN_MONITOR.isApiKeyUsageEnabled ? (
+ <Route path="api-key-usage">
+ {PLUGIN_MONITOR.getApiKeyUsageRoutes()}
+ </Route>
+ ) : (
+ <Route path="api-key-usage">
+ <Route index lazy={apiKeyUsageUpsellPage} />
+ <Route path="*" lazy={apiKeyUsageUpsellPage} />
+ </Route>
+ )}
+ </Route>
+
<Route element={<CanAccessAlertsManagement />}>
<Route path="notifications">{getNotificationsRoutes()}</Route>
</Route>
diff --git a/frontend/src/metabase/monitor/routes.unit.spec.tsx b/frontend/src/metabase/monitor/routes.unit.spec.tsx
index fe3874660af..6072be3bda7 100644
--- a/frontend/src/metabase/monitor/routes.unit.spec.tsx
+++ b/frontend/src/metabase/monitor/routes.unit.spec.tsx
@@ -6,7 +6,7 @@ describe("monitor routes", () => {
it("resolves every page", async () => {
const loaders = lazyLoaders(getMonitorRoutes());
- expect(loaders).toHaveLength(15);
+ expect(loaders).toHaveLength(17);
for (const load of loaders) {
expect((await load()).Component).toBeDefined();
diff --git a/frontend/src/metabase/plugins/oss/monitor.ts b/frontend/src/metabase/plugins/oss/monitor.ts
index e6195932c32..afc9aa3904d 100644
--- a/frontend/src/metabase/plugins/oss/monitor.ts
+++ b/frontend/src/metabase/plugins/oss/monitor.ts
@@ -7,6 +7,8 @@ type MonitorPlugin = {
getDependencyDiagnosticsRoutes: () => ReactNode;
isSessionManagementEnabled: boolean;
getSessionManagementRoutes: () => ReactNode;
+ isApiKeyUsageEnabled: boolean;
+ getApiKeyUsageRoutes: () => ReactNode;
};
const getDefaultPluginMonitor = (): MonitorPlugin => ({
@@ -14,6 +16,8 @@ const getDefaultPluginMonitor = (): MonitorPlugin => ({
getDependencyDiagnosticsRoutes: () => null,
isSessionManagementEnabled: false,
getSessionManagementRoutes: () => null,
+ isApiKeyUsageEnabled: false,
+ getApiKeyUsageRoutes: () => null,
});
export const PLUGIN_MONITOR = definePluginSlot(getDefaultPluginMonitor);
diff --git a/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableHeader/TreeTableHeader.module.css b/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableHeader/TreeTableHeader.module.css
index 5c3b5603e13..1973871ac2d 100644
--- a/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableHeader/TreeTableHeader.module.css
+++ b/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableHeader/TreeTableHeader.module.css
@@ -11,6 +11,7 @@
.headerRow {
border-bottom: 1px solid var(--mb-color-border-neutral);
background-color: var(--mb-color-background_page-primary);
+ user-select: none;
}
.cell {
diff --git a/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableRow/TreeTableRow.module.css b/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableRow/TreeTableRow.module.css
index dea369589d5..cdb513fa612 100644
--- a/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableRow/TreeTableRow.module.css
+++ b/frontend/src/metabase/ui/components/data-display/TreeTable/TreeTableRow/TreeTableRow.module.css
@@ -29,6 +29,7 @@
.content {
display: flex;
+ user-select: none;
&:hover {
background-color: var(--mb-color-background_surface-hover);
@@ -68,12 +69,14 @@
.treeCell {
overflow: hidden;
+ user-select: text;
}
.cell {
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
+ user-select: text;
}
.link {
diff --git a/frontend/src/metabase/urls/monitor.ts b/frontend/src/metabase/urls/monitor.ts
index 4bb2e97fdd2..f044448e556 100644
--- a/frontend/src/metabase/urls/monitor.ts
+++ b/frontend/src/metabase/urls/monitor.ts
@@ -142,3 +142,15 @@ export function monitorAiAuditingCliUsage() {
export function monitorAiAuditingCliCalls() {
return `${monitorAiAuditingCli()}/calls`;
}
+
+export function monitorApiKeyUsage() {
+ return `${ROOT_URL}/api-key-usage`;
+}
+
+export function monitorApiKeyUsageOverview() {
+ return `${monitorApiKeyUsage()}/usage`;
+}
+
+export function monitorApiKeyUsageEvents() {
+ return `${monitorApiKeyUsage()}/events`;
+}
diff --git a/resources/frontend_client/app/assets/img/upsell-api-usage-analytics.png b/resources/frontend_client/app/assets/img/upsell-api-usage-analytics.png
new file mode 100644
index 00000000000..c82f8195d26
Binary files /dev/null and b/resources/frontend_client/app/assets/img/upsell-api-usage-analytics.png differ
diff --git a/resources/migrations/065/20260907_api_key_usage_analytics.yaml b/resources/migrations/065/20260907_api_key_usage_analytics.yaml
new file mode 100644
index 00000000000..1d84c92d82b
--- /dev/null
+++ b/resources/migrations/065/20260907_api_key_usage_analytics.yaml
@@ -0,0 +1,163 @@
+## API Key usage analytics storage layer.
+##
+## Two pieces:
+## - api_key.last_used_at — cheap liveness for "is this key still in use?", updated in place.
+## - api_key_usage_log — one row per API-key-authenticated request, modeled on
+## agent_api_call_log / mcp_tool_call_log.
+##
+## The log row carries the resolved user and the key's real creator so the view needs no join back
+## to api_key, which lets rows outlive a deleted key. `user_id` is the key's own synthetic
+## service-account user (used for permission checks); `created_by_id` is the real human who created
+## the key. `route_template` is the reconstructed Compojure route (e.g. /api/card/:id), never the raw
+## URI or query string — those carry entity ids and filter values.
+
+databaseChangeLog:
+ - logicalFilePath: migrations/065_update_migrations.yaml
+
+ - changeSet:
+ id: v65.2026-09-07T00:00:00
+ author: sfragnaud
+ comment: Add api_key.last_used_at
+ changes:
+ - addColumn:
+ tableName: api_key
+ columns:
+ - column:
+ name: last_used_at
+ type: ${timestamp_type}
+ remarks: When this API key was last used to authenticate a request; NULL until first use. Updated in place (throttled), not per request.
+ constraints:
+ nullable: true
+
+ - changeSet:
+ id: v65.2026-09-07T00:00:01
+ author: sfragnaud
+ comment: Create api_key_usage_log table
+ changes:
+ - createTable:
+ tableName: api_key_usage_log
+ remarks: One row per API-key-authenticated request; user and key creator denormalized on so the view needs no api_key join (modeled on agent_api_call_log)
+ columns:
+ - column:
+ name: id
+ type: bigint
+ autoIncrement: true
+ remarks: Autoincrement primary key
+ constraints:
+ primaryKey: true
+ nullable: false
+ - column:
+ name: api_key_id
+ type: int
+ remarks: The API key that authenticated the request. Deliberately not a foreign key so deleting a key does not cascade away its usage history.
+ constraints:
+ nullable: false
+ - column:
+ name: user_id
+ type: int
+ remarks: The API key's own synthetic service-account user, resolved at request time; NULL when the key has no user. Used for permission checks, not a real person. Not a foreign key, for the same reason as api_key_id. Non-PII.
+ constraints:
+ nullable: true
+ - column:
+ name: created_by_id
+ type: int
+ remarks: The real human who created the API key, resolved from the same auth query as user_id; NULL when the key has no user. Not a foreign key, for the same reason as api_key_id. Non-PII.
+ constraints:
+ nullable: true
+ - column:
+ name: route_template
+ type: varchar(255)
+ remarks: Reconstructed route template of the request, e.g. /api/card/:id. Never the raw URI or query string. Non-PII.
+ constraints:
+ nullable: false
+ - column:
+ name: http_method
+ type: varchar(10)
+ remarks: HTTP method of the request, e.g. GET or POST. Non-PII.
+ constraints:
+ nullable: false
+ - column:
+ name: status
+ type: int
+ remarks: HTTP status code of the response. Non-PII. Streamed responses (for example query results) always store 202, because the real status is only known after the stream ends, so do not read 202 as an outcome.
+ constraints:
+ nullable: false
+ - column:
+ name: duration_ms
+ type: int
+ remarks: Wall-clock duration of the request in milliseconds
+ constraints:
+ nullable: false
+ - column:
+ name: occurred_at
+ type: ${timestamp_type}
+ defaultValueComputed: current_timestamp
+ remarks: When the request happened, captured on the request thread. The default is a fallback only — the recorder always sets this explicitly, since the row itself may not land in the table until a scheduled flush later.
+ constraints:
+ nullable: false
+ - column:
+ name: ip_address
+ type: varchar(45)
+ remarks: Client IP captured at request time, PII (gated by analytics-pii-retention-enabled).
+ constraints:
+ nullable: true
+ - column:
+ name: user_agent
+ type: varchar(512)
+ remarks: Raw User-Agent header captured at request time, PII (gated by analytics-pii-retention-enabled).
+ constraints:
+ nullable: true
+ - column:
+ name: client_name
+ type: varchar(255)
+ remarks: Caller classified from the raw User-Agent (metabase-cli, curl, postman, python-requests, r, node, or other). Non-PII, always recorded — distinct from the raw, PII-gated user_agent column.
+ constraints:
+ nullable: false
+ - column:
+ name: embedding_client
+ type: varchar(255)
+ remarks: Raw X-Metabase-Client header value, when present. Non-PII, same status as view_log/query_execution.embedding_client. Supplementary to client_name (the primary classification axis) — almost never set on API-key traffic, since the SDK/embed.js clients that send it authenticate via JWT/SSO, not API keys.
+ constraints:
+ nullable: true
+ rollback:
+ - dropTable:
+ tableName: api_key_usage_log
+
+ - changeSet:
+ id: v65.2026-09-07T00:00:02
+ author: sfragnaud
+ comment: Index on api_key_usage_log.api_key_id
+ changes:
+ - createIndex:
+ indexName: idx_api_key_usage_log_api_key_id
+ tableName: api_key_usage_log
+ columns:
+ - column:
+ name: api_key_id
+ rollback: # dropped with table
+
+ - changeSet:
+ id: v65.2026-09-07T00:00:03
+ author: sfragnaud
+ comment: Index on api_key_usage_log.created_by_id
+ changes:
+ - createIndex:
+ indexName: idx_api_key_usage_log_created_by_id
+ tableName: api_key_usage_log
+ columns:
+ - column:
+ name: created_by_id
+ rollback: # dropped with table
+
+ - changeSet:
+ id: v65.2026-09-07T00:00:04
+ author: sfragnaud
+ comment: Index on api_key_usage_log.occurred_at
+ changes:
+ - createIndex:
+ indexName: idx_api_key_usage_log_occurred_at
+ tableName: api_key_usage_log
+ columns:
+ - column:
+ name: occurred_at
+ rollback: # dropped with table
diff --git a/resources/migrations/065/20260908_api_key_usage_analytics_embedding_hostname.yaml b/resources/migrations/065/20260908_api_key_usage_analytics_embedding_hostname.yaml
new file mode 100644
index 00000000000..6d29b2d4f32
--- /dev/null
+++ b/resources/migrations/065/20260908_api_key_usage_analytics_embedding_hostname.yaml
@@ -0,0 +1,35 @@
+## Add embedding_hostname to api_key_usage_log.
+##
+## The createTable changeset for api_key_usage_log (20260907_api_key_usage_analytics.yaml) already
+## shipped as far as this branch's own ancestry is concerned — editing it in place, like the earlier
+## client_name/embedding_client columns did, would change its checksum out from under any branch
+## that already recorded it. That's a real (not just style) requirement: Liquibase validates a
+## changeset's checksum against what was previously applied, and CI's cross-branch-migration-test
+## boots this PR's base branch first, then this PR's branch, so any downstream edit to an
+## already-applied changeset fails validation. A new column always needs a new changeset here.
+##
+## Filename intentionally sorts between the table-creation migration (20260907) and the view
+## migration (20260910) — includeAll processes files alphabetically, and the view's SELECT
+## references this column, so the column must exist before the view is (re)created.
+
+databaseChangeLog:
+ - logicalFilePath: migrations/065_update_migrations.yaml
+
+ - changeSet:
+ id: v65.2026-09-08T00:00:00
+ author: sfragnaud
+ comment: Add embedding_hostname to api_key_usage_log
+ changes:
+ - addColumn:
+ tableName: api_key_usage_log
+ columns:
+ - column:
+ name: embedding_hostname
+ type: varchar(512)
+ remarks: Hostname parsed from the embed referrer header, when present. Non-PII, same status as view_log/query_execution/metabot_conversation.embedding_hostname. Only meaningful alongside embedding_client.
+ constraints:
+ nullable: true
+ rollback:
+ - dropColumn:
+ tableName: api_key_usage_log
+ columnName: embedding_hostname
diff --git a/resources/migrations/065/20260910_api_key_usage_analytics_view.yaml b/resources/migrations/065/20260910_api_key_usage_analytics_view.yaml
new file mode 100644
index 00000000000..9bebfbae35f
--- /dev/null
+++ b/resources/migrations/065/20260910_api_key_usage_analytics_view.yaml
@@ -0,0 +1,35 @@
+## Create the v_api_key_usage view for API-key usage analytics.
+##
+## Filename intentionally sorts after 20260907_api_key_usage_analytics.yaml (the table-creation
+## migration) so Liquibase — which processes change-log files alphabetically — creates the
+## api_key_usage_log table before this view references it.
+##
+## Client identity + PII are stored on each request row, so v_api_key_usage reads them straight off
+## api_key_usage_log. Every join is a LEFT JOIN: api_key_usage_log deliberately has no foreign keys
+## on api_key_id / user_id / created_by_id so rows outlive a deleted key or user — an inner join
+## would silently drop that history, so api_key_name / creator_display_name / group_name are simply
+## NULL once the referenced row is gone.
+
+databaseChangeLog:
+ - logicalFilePath: migrations/065_update_migrations.yaml
+
+ - changeSet:
+ id: v65.2026-09-10T00:00:10
+ author: sfragnaud
+ runOnChange: true
+ comment: Create v_api_key_usage view for API-key usage analytics
+ changes:
+ - sqlFile:
+ dbms: postgresql
+ path: ../instance_analytics_views/api_key_usage/v1/postgres-api_key_usage.sql
+ relativeToChangelogFile: true
+ - sqlFile:
+ dbms: mysql,mariadb
+ path: ../instance_analytics_views/api_key_usage/v1/mysql-api_key_usage.sql
+ relativeToChangelogFile: true
+ - sqlFile:
+ dbms: h2
+ path: ../instance_analytics_views/api_key_usage/v1/h2-api_key_usage.sql
+ relativeToChangelogFile: true
+ rollback:
+ - sql: DROP VIEW IF EXISTS v_api_key_usage
diff --git a/resources/migrations/instance_analytics_views/api_key_usage/v1/h2-api_key_usage.sql b/resources/migrations/instance_analytics_views/api_key_usage/v1/h2-api_key_usage.sql
new file mode 100644
index 00000000000..fde5ff8ab30
--- /dev/null
+++ b/resources/migrations/instance_analytics_views/api_key_usage/v1/h2-api_key_usage.sql
@@ -0,0 +1,52 @@
+DROP VIEW IF EXISTS v_api_key_usage;
+
+CREATE OR REPLACE VIEW v_api_key_usage AS
+SELECT
+ t.id AS log_id,
+ t.occurred_at,
+ t.route_template,
+ t.http_method,
+ t.status,
+ t.duration_ms,
+ t.api_key_id AS api_key_id,
+ ak.name AS api_key_name,
+ -- actor: who/what authenticated the request (the key's own synthetic service-account user).
+ t.user_id AS actor_user_id,
+ -- creator: the real human who made the key — a different person from the actor above.
+ t.created_by_id AS creator_id,
+ -- CAST to VARCHAR: H2 declares core_user.email VARCHAR_IGNORECASE (for case-insensitive lookups),
+ -- and COALESCE inherits that type, which Metabase's H2 type mapper doesn't recognize — it falls back
+ -- to an unknown type, and metabase-lib silently excludes unknown-typed columns from sortable columns.
+ CAST(COALESCE(creator.first_name || ' ' || creator.last_name, creator.email) AS VARCHAR) AS creator_display_name,
+ -- the key's own group (via its synthetic user ak.user_id), not the creator's — a key has
+ -- exactly one group, but its creator may belong to several. Ordered so a specific group
+ -- (id != 1) wins over All Users when the key is in both, rather than excluding All Users
+ -- outright — a key whose only group is All Users would otherwise get a NULL group_name.
+ (SELECT pg.name
+ FROM permissions_group_membership pgm
+ JOIN permissions_group pg ON pg.id = pgm.group_id
+ WHERE pgm.user_id = ak.user_id
+ ORDER BY CASE WHEN pg.id = 1 THEN 1 ELSE 0 END, pg.name
+ LIMIT 1) AS group_name,
+ t.client_name AS client_name,
+ -- NOTE: keep these CASE branches in sync with `supported-client-keys` /
+ -- `detect-client` in src/metabase/api_keys/usage.clj (the enum-<->-CASE sync footgun).
+ CASE t.client_name
+ WHEN 'metabase-cli' THEN 'Metabase CLI'
+ WHEN 'curl' THEN 'curl'
+ WHEN 'postman' THEN 'Postman'
+ WHEN 'python-requests' THEN 'Python'
+ WHEN 'r' THEN 'R'
+ WHEN 'node' THEN 'Node.js'
+ WHEN 'other' THEN 'Other'
+ ELSE t.client_name
+ END AS client_display_name,
+ t.embedding_client AS embedding_client,
+ t.embedding_hostname AS embedding_hostname,
+ t.ip_address AS ip_address,
+ t.user_agent AS user_agent
+FROM api_key_usage_log t
+LEFT JOIN api_key ak
+ ON ak.id = t.api_key_id
+LEFT JOIN core_user creator
+ ON creator.id = t.created_by_id;
diff --git a/resources/migrations/instance_analytics_views/api_key_usage/v1/mysql-api_key_usage.sql b/resources/migrations/instance_analytics_views/api_key_usage/v1/mysql-api_key_usage.sql
new file mode 100644
index 00000000000..6e74dd94e70
--- /dev/null
+++ b/resources/migrations/instance_analytics_views/api_key_usage/v1/mysql-api_key_usage.sql
@@ -0,0 +1,49 @@
+DROP VIEW IF EXISTS v_api_key_usage;
+
+CREATE OR REPLACE VIEW v_api_key_usage AS
+SELECT
+ t.id AS log_id,
+ t.occurred_at,
+ t.route_template,
+ t.http_method,
+ t.status,
+ t.duration_ms,
+ t.api_key_id AS api_key_id,
+ ak.name AS api_key_name,
+ -- actor: who/what authenticated the request (the key's own synthetic service-account user).
+ t.user_id AS actor_user_id,
+ -- creator: the real human who made the key — a different person from the actor above.
+ t.created_by_id AS creator_id,
+ COALESCE(CONCAT(creator.first_name, ' ', creator.last_name), creator.email) AS creator_display_name,
+ -- the key's own group (via its synthetic user ak.user_id), not the creator's — a key has
+ -- exactly one group, but its creator may belong to several. Ordered so a specific group
+ -- (id != 1) wins over All Users when the key is in both, rather than excluding All Users
+ -- outright — a key whose only group is All Users would otherwise get a NULL group_name.
+ (SELECT pg.name
+ FROM permissions_group_membership pgm
+ JOIN permissions_group pg ON pg.id = pgm.group_id
+ WHERE pgm.user_id = ak.user_id
+ ORDER BY CASE WHEN pg.id = 1 THEN 1 ELSE 0 END, pg.name
+ LIMIT 1) AS group_name,
+ t.client_name AS client_name,
+ -- NOTE: keep these CASE branches in sync with `supported-client-keys` /
+ -- `detect-client` in src/metabase/api_keys/usage.clj (the enum-<->-CASE sync footgun).
+ CASE t.client_name
+ WHEN 'metabase-cli' THEN 'Metabase CLI'
+ WHEN 'curl' THEN 'curl'
+ WHEN 'postman' THEN 'Postman'
+ WHEN 'python-requests' THEN 'Python'
+ WHEN 'r' THEN 'R'
+ WHEN 'node' THEN 'Node.js'
+ WHEN 'other' THEN 'Other'
+ ELSE t.client_name
+ END AS client_display_name,
+ t.embedding_client AS embedding_client,
+ t.embedding_hostname AS embedding_hostname,
+ t.ip_address AS ip_address,
+ t.user_agent AS user_agent
+FROM api_key_usage_log t
+LEFT JOIN api_key ak
+ ON ak.id = t.api_key_id
+LEFT JOIN core_user creator
+ ON creator.id = t.created_by_id;
diff --git a/resources/migrations/instance_analytics_views/api_key_usage/v1/postgres-api_key_usage.sql b/resources/migrations/instance_analytics_views/api_key_usage/v1/postgres-api_key_usage.sql
new file mode 100644
index 00000000000..21edcdcf3e2
--- /dev/null
+++ b/resources/migrations/instance_analytics_views/api_key_usage/v1/postgres-api_key_usage.sql
@@ -0,0 +1,49 @@
+DROP VIEW IF EXISTS v_api_key_usage;
+
+CREATE OR REPLACE VIEW v_api_key_usage AS
+SELECT
+ t.id AS log_id,
+ t.occurred_at,
+ t.route_template,
+ t.http_method,
+ t.status,
+ t.duration_ms,
+ t.api_key_id AS api_key_id,
+ ak.name AS api_key_name,
+ -- actor: who/what authenticated the request (the key's own synthetic service-account user).
+ t.user_id AS actor_user_id,
+ -- creator: the real human who made the key — a different person from the actor above.
+ t.created_by_id AS creator_id,
+ COALESCE(creator.first_name || ' ' || creator.last_name, creator.email) AS creator_display_name,
+ -- the key's own group (via its synthetic user ak.user_id), not the creator's — a key has
+ -- exactly one group, but its creator may belong to several. Ordered so a specific group
+ -- (id != 1) wins over All Users when the key is in both, rather than excluding All Users
+ -- outright — a key whose only group is All Users would otherwise get a NULL group_name.
+ (SELECT pg.name
+ FROM permissions_group_membership pgm
+ JOIN permissions_group pg ON pg.id = pgm.group_id
+ WHERE pgm.user_id = ak.user_id
+ ORDER BY CASE WHEN pg.id = 1 THEN 1 ELSE 0 END, pg.name
+ LIMIT 1) AS group_name,
+ t.client_name AS client_name,
+ -- NOTE: keep these CASE branches in sync with `supported-client-keys` /
+ -- `detect-client` in src/metabase/api_keys/usage.clj (the enum-<->-CASE sync footgun).
+ CASE t.client_name
+ WHEN 'metabase-cli' THEN 'Metabase CLI'
+ WHEN 'curl' THEN 'curl'
+ WHEN 'postman' THEN 'Postman'
+ WHEN 'python-requests' THEN 'Python'
+ WHEN 'r' THEN 'R'
+ WHEN 'node' THEN 'Node.js'
+ WHEN 'other' THEN 'Other'
+ ELSE t.client_name
+ END AS client_display_name,
+ t.embedding_client AS embedding_client,
+ t.embedding_hostname AS embedding_hostname,
+ t.ip_address AS ip_address,
+ t.user_agent AS user_agent
+FROM api_key_usage_log t
+LEFT JOIN api_key ak
+ ON ak.id = t.api_key_id
+LEFT JOIN core_user creator
+ ON creator.id = t.created_by_id;
diff --git a/src/metabase/api/macros.clj b/src/metabase/api/macros.clj
index 24353ee13c5..ff9cce3131c 100644
--- a/src/metabase/api/macros.clj
+++ b/src/metabase/api/macros.clj
@@ -870,32 +870,64 @@
[:map-of ::method [:sequential [:tuple
(ms/InstanceOfClass clout.core.CompiledRoute)
::handler
- [:maybe ::route-metadata]]]])
+ [:maybe ::route-metadata]
+ #_route-path :string]]])
(mu/defn- ns-handler-map :- ::handler-map
- "Build a map of method => [[clout-route handler metadata]+] used to power the combined ns handler built
- by [[build-ns-handler]]."
+ "Build a map of method => [[clout-route handler metadata route-path]+] used to power the combined ns handler built
+ by [[build-ns-handler]].
+
+ `route-path` is the raw (uncompiled) Clout pattern the endpoint declared, e.g. `\"/:id\"`. Route-param regexes are
+ compiled into the [[clout.core.CompiledRoute]] but deliberately kept out of `route-path`, so it holds placeholder
+ names only — that is what [[route-template]] needs."
[endpoints :- ::ns-endpoints]
(->> endpoints
vals
(group-by #(get-in % [:form :method]))
(m/map-vals (fn [routes]
(mapv (fn [route]
- [(clout/route-compile (get-in route [:form :route :path])
- (update-keys (get-in route [:form :route :regexes] {}) keyword))
- (:handler route)
- (get-in route [:form :metadata])])
+ (let [path (get-in route [:form :route :path])]
+ [(clout/route-compile path (update-keys (get-in route [:form :route :regexes] {}) keyword))
+ (:handler route)
+ (get-in route [:form :metadata])
+ path]))
routes)))))
(defn- decode-route-params [route-params]
(update-vals route-params ring.util.codec/url-decode))
+(defn- request-route-prefix
+ "Route prefix accumulated for `request` so far: the [[metabase.api.util.handlers/route-map-handler]] levels it
+ descended through, or — for an ns handler mounted straight under a `compojure.core/context` with no route map in
+ between — the context patterns alone."
+ [request]
+ (or (:route-prefix request)
+ (:compojure/route-context request)))
+
+(mu/defn- route-template :- :string
+ "Reconstruct the full route template for a matched endpoint, e.g. `\"/api/card/:id\"`.
+
+ `route-prefix` is the prefix accumulated by [[metabase.api.util.handlers/route-map-handler]] as routing descended
+ (seeded with the enclosing `compojure.core/context` patterns, so `/api` is included); `route-path` is the
+ ns-relative Clout pattern the endpoint declared.
+
+ This is built purely from declared route structure. It never contains request values — no query string, no
+ `:query-params`, and no concrete path-param values — which is what makes it safe to store for analytics."
+ [route-prefix :- [:maybe :string]
+ route-path :- :string]
+ (let [prefix (or route-prefix "")]
+ ;; A `\"/\"` endpoint is the prefix itself (`GET /api/card` matches the `\"/\"` route of `metabase.queries-rest.api`
+ ;; because each route-map level leaves `\"/\"` behind), so don't tack on a meaningless trailing slash.
+ (if (= route-path "/")
+ (if (str/blank? prefix) "/" prefix)
+ (str prefix route-path))))
+
(mu/defn- find-matching-handler :- [:maybe [:tuple ::request ::handler]]
"Find the appropriate handler from `handler-map` to handle `request`. Returns a tuple of
[request' handler]
- (Request is updated to include parsed Clout parameters and route metadata.)"
+ (Request is updated to include parsed Clout parameters, route metadata, and the reconstructed `:route-template`.)"
[handler-map :- ::handler-map
request :- ::request]
(let [request-method (:request-method request)
@@ -904,14 +936,31 @@
request (cond-> request
path (assoc :path-info path))]
;; TODO -- we could probably make this a little faster by unrolling this loop
- (some (fn [[route handler metadata]]
+ (some (fn [[route handler metadata route-path]]
(when-let [route-params (clout/route-matches route request)]
[(-> request
(assoc :route-params (decode-route-params route-params))
- (assoc :route-metadata metadata))
+ (assoc :route-metadata metadata)
+ (assoc :route-template (route-template (request-route-prefix request) route-path)))
handler]))
handlers)))
+(def route-template-carrier-key
+ "Request key under which middleware running *above* the routing tree can put a `volatile!` in order to learn which
+ route template ended up matching.
+
+ `:route-template` is added to a request that routing builds for the matched endpoint alone
+ (see [[find-matching-handler]]); it never travels back up, and neither does anything else reliable. Response
+ metadata would cover successful responses, but an endpoint that throws — which is how most 4xx/5xx are produced —
+ has its response built from the exception by `metabase.server.middleware.exceptions/catch-api-exceptions`, losing
+ any metadata the endpoint's response would have carried. A carrier owned by the outer middleware covers both, the
+ same way `log-api-call` already collects DB call counts from deep inside a request.
+
+ The carrier is optional: routing pays a single map lookup regardless, whether or not one is installed. See
+ `metabase.server.middleware.route-template-carrier/wrap-route-template-carrier`, which installs one
+ unconditionally on every request."
+ ::route-template-carrier)
+
(mu/defn- build-ns-handler :- ::handler
"Build a combined Ring handler for all `endpoints` that routes requests to the matching handler (if any)."
[endpoints :- ::ns-endpoints]
@@ -919,7 +968,9 @@
(open-api/handler-with-open-api-spec
(fn ns-handler* [request respond raise]
(if-let [[request* handler] (find-matching-handler handler-map request)]
- (handler request* respond raise)
+ (do
+ (some-> (get request route-template-carrier-key) (vreset! (:route-template request*)))
+ (handler request* respond raise))
(respond nil)))
(fn [prefix]
(metabase.api.macros.defendpoint.open-api/open-api-spec endpoints prefix)))))
diff --git a/src/metabase/api/util/handlers.clj b/src/metabase/api/util/handlers.clj
index 47227f47fd6..c50283931e6 100644
--- a/src/metabase/api/util/handlers.clj
+++ b/src/metabase/api/util/handlers.clj
@@ -15,11 +15,24 @@
[(subs path 0 next-slash-index) (subs path next-slash-index (count path))]
[path "/"])))
+(defn- route-prefix
+ "The `:route-prefix` for `request` after this route-map level consumed `prefix`.
+
+ The first route-map level seeds the accumulator from `:compojure/route-context` — the route *patterns* of the
+ enclosing `compojure.core/context` forms, which is how the leading `/api`
+ from [[metabase.server.routes/make-routes]] gets into the template. We use `:compojure/route-context` rather than
+ Ring's `:context` because `:context` is sliced out of the request URI and would carry real path-param values for a
+ parameterized context; `:compojure/route-context` is always the declared pattern."
+ [request prefix]
+ (str (or (:route-prefix request) (:compojure/route-context request)) prefix))
+
(defn- -route-map-handler [route-map]
(fn [request respond raise]
(if-let [[prefix rest-of-path] (split-path ((some-fn :path-info :uri) request))]
(if-let [handler (get route-map prefix)]
- (let [request' (assoc request :path-info rest-of-path)]
+ (let [request' (-> request
+ (assoc :path-info rest-of-path)
+ (assoc :route-prefix (route-prefix request prefix)))]
(handler request' respond raise))
(respond nil))
(respond nil))))
@@ -46,7 +59,11 @@
(simple-symbol? v) api.macros/ns-handler))))
(defn route-map-handler
- "Create a Ring handler from a map of route prefix => handler."
+ "Create a Ring handler from a map of route prefix => handler.
+
+ As routing descends, each level appends the prefix it consumed to the request's `:route-prefix`, which
+ `metabase.api.macros` turns into the matched request's `:route-template` (e.g. `\"/api/card/:id\"`). Only declared
+ route patterns are accumulated — never anything from the request URI or query string."
[route-map]
(let [route-map (prepare-route-map route-map)]
(open-api/handler-with-open-api-spec
diff --git a/src/metabase/api_keys/api.clj b/src/metabase/api_keys/api.clj
index 0b2491a038b..a65f3989ea5 100644
--- a/src/metabase/api_keys/api.clj
+++ b/src/metabase/api_keys/api.clj
@@ -29,7 +29,8 @@
:group
:unmasked_key
:name
- :masked_key])
+ :masked_key
+ :last_used_at])
(maybe-expose-key)
(update :updated_by #(select-keys % [:common_name :id]))))
diff --git a/src/metabase/api_keys/core.clj b/src/metabase/api_keys/core.clj
index e9edf04f565..4975a17a800 100644
--- a/src/metabase/api_keys/core.clj
+++ b/src/metabase/api_keys/core.clj
@@ -1,9 +1,12 @@
(ns metabase.api-keys.core
(:require
+ [metabase.api-keys.db]
[metabase.api-keys.models.api-key]
[potemkin :as p]))
-(comment metabase.api-keys.models.api-key/keep-me)
+(comment
+ metabase.api-keys.models.api-key/keep-me
+ metabase.api-keys.db/keep-me)
(p/import-vars
[metabase.api-keys.models.api-key
@@ -11,3 +14,7 @@
is-api-key-user?
prefix
create-api-key-with-new-user!])
+
+(p/import-vars
+ [metabase.api-keys.db
+ update-api-keys-last-used-at!])
diff --git a/src/metabase/api_keys/db.clj b/src/metabase/api_keys/db.clj
index b651de0c3ea..402a50c1716 100644
--- a/src/metabase/api_keys/db.clj
+++ b/src/metabase/api_keys/db.clj
@@ -2,8 +2,10 @@
"Application database queries for the API keys module. Every function here is a direct Toucan 2 call with no
additional logic, so no other namespace in the module runs a query itself (model definitions still use `toucan2.core`)."
(:require
+ [java-time.api :as t]
[malli.util :as mut]
[metabase.api-keys.schema :as api-keys.schema]
+ [metabase.app-db.core :as mdb]
[metabase.lib.schema.id :as lib.schema.id]
[metabase.users.schema :as users.schema]
[metabase.util.malli :as mu]
@@ -16,9 +18,15 @@
(t2/count :model/ApiKey :scope nil))
(mu/defn unscoped-api-keys
- "The ApiKeys without a scope."
+ "The ApiKeys without a scope, most recently used first (nulls last — a key never used sorts after
+ every key that has been)."
[]
- (t2/select :model/ApiKey :scope nil))
+ (t2/select :model/ApiKey :scope nil
+ {:order-by [[:last_used_at (case (mdb/db-type)
+ ;; NULLS LAST isn't valid MySQL syntax, but MySQL already sorts
+ ;; NULLs last on DESC by default (it treats NULL as the lowest value).
+ (:postgres :h2) :desc-nulls-last
+ :mysql :desc)]]}))
(mu/defn api-key
"The ApiKey with `id`, or nil."
@@ -98,3 +106,47 @@
[id :- ms/PositiveInt
changes :- (mut/select-keys ::api-keys.schema/api-key.update [:key :key_prefix :updated_by_id])]
(t2/update! :model/ApiKey :id id changes))
+
+(defn lock-available-key-ids
+ "The subset of `ids` not currently locked by another writer, locked for update (`SKIP LOCKED` outside
+ H2, whose single-connection test usage neither needs nor supports it). Public so tests can simulate a
+ busy row by redefining it, without real cross-connection lock contention."
+ [ids]
+ (map :id (t2/query (cond-> {:select [:id]
+ :from [(t2/table-name :model/ApiKey)]
+ :where [:in :id ids]}
+ (not= :h2 (mdb/db-type)) (assoc :for [:update :skip-locked])))))
+
+(defn update-api-keys-last-used-at!
+ "Move `last_used_at` of each ApiKey in `id->timestamp` forward to its timestamp, without touching
+ `updated_at`. Returns the subset of `id->timestamp` that was skipped because another writer held the
+ row — the caller should retry those on its next pass rather than wait for them here. A deleted key's
+ id is dropped rather than retried: it never comes back from [[lock-available-key-ids]], but it is
+ gone for good, not merely busy, so retrying it on every flush would never succeed.
+
+ Locks the rows first with `SELECT ... FOR UPDATE SKIP LOCKED` (outside H2) so a key a concurrent
+ writer is editing (e.g. an admin renaming or rotating it) is skipped rather than blocking this
+ UPDATE — and, by extension, every unrelated key batched alongside it — until that writer's
+ transaction commits.
+
+ A plain UPDATE rather than [[update-api-key!]] on purpose: the model's `before-update` hook hydrates
+ the key and publishes an `:event/api-key-update` audit event, which a usage stamp must not do.
+ Mirrors [[metabase.query-processor.db/update-cards-last-used-at!]]'s bulk `CASE`/`GREATEST` pattern
+ for the same reason: many keys land in one batch, and this is one UPDATE for all of them rather than
+ one per key."
+ [id->timestamp]
+ (t2/with-transaction [_conn]
+ (let [available-ids (lock-available-key-ids (keys id->timestamp))]
+ (when (seq available-ids)
+ (t2/query {:update [(t2/table-name :model/ApiKey)]
+ :where [:in :id available-ids]
+ :set {:last_used_at (into [:case]
+ (mapcat (fn [id]
+ [[:= :id id]
+ [:greatest [:coalesce :last_used_at (t/offset-date-time 0)]
+ (get id->timestamp id)]])
+ available-ids))
+ :updated_at :updated_at}}))
+ (select-keys id->timestamp
+ (when-let [busy (seq (remove (set available-ids) (keys id->timestamp)))]
+ (t2/select-pks-set :model/ApiKey :id [:in busy]))))))
diff --git a/src/metabase/api_keys/models/api_key_usage_log.clj b/src/metabase/api_keys/models/api_key_usage_log.clj
new file mode 100644
index 00000000000..4f85daafc00
--- /dev/null
+++ b/src/metabase/api_keys/models/api_key_usage_log.clj
@@ -0,0 +1,9 @@
+(ns metabase.api-keys.models.api-key-usage-log
+ (:require
+ [methodical.core :as methodical]
+ [toucan2.core :as t2]))
+
+(methodical/defmethod t2/table-name :model/ApiKeyUsageLog [_model] :api_key_usage_log)
+
+(doto :model/ApiKeyUsageLog
+ (derive :metabase/model))
diff --git a/src/metabase/api_keys/schema.clj b/src/metabase/api_keys/schema.clj
index 9546861c27a..61ba196c0a2 100644
--- a/src/metabase/api_keys/schema.clj
+++ b/src/metabase/api_keys/schema.clj
@@ -106,6 +106,7 @@
[:updated_by_id pos-int?]
[:scope {:optional true} [:maybe [:ref ::scope]]]
[:single_collection_id {:optional true} [:maybe pos-int?]]
+ [:last_used_at {:optional true} [:maybe [:ref ::timestamp]]]
;; added by the model's after-select hook
[:masked_key {:optional true} :string]])
diff --git a/src/metabase/api_keys/usage.clj b/src/metabase/api_keys/usage.clj
new file mode 100644
index 00000000000..48fc8d4daa3
--- /dev/null
+++ b/src/metabase/api_keys/usage.clj
@@ -0,0 +1,88 @@
+(ns metabase.api-keys.usage
+ "API-key usage logging.
+
+ One entry point, [[record-api-key-usage!]], feeds two things per API-key-authenticated `/api/*`
+ request: a lean `api_key_usage_log` row, and an `api_key.last_used_at` stamp that answers \"is this
+ key still in use?\" cheaply. Callers don't need to know there are two internal write strategies —
+ see `metabase-enterprise.api-keys.usage` for why they're split and how each is batched. This is a
+ `defenterprise` no-op in OSS — an OSS instance records nothing — with the real writes in
+ `metabase-enterprise.api-keys.usage`. Like `ai_usage_log`, collection runs on every EE instance
+ (`:feature :none`); the `:audit-app` feature gates the surfaces that read these rows, not the
+ writing.
+
+ The function takes the raw Ring `request`/`response` and extracts everything itself; the caller
+ (the `log-api-call` hook) supplies only the handful of values it alone can compute — see
+ `metabase-enterprise.api-keys.usage/record-api-key-usage!`'s docstring for the `extra-info` shape.
+
+ PII columns (`ip_address`, `user_agent`) are populated only when `analytics-pii-retention-enabled`
+ is on — a setting that is itself `:audit-app`-gated and defaults off, so PII is never collected
+ without `:audit-app`. `route_template` is the reconstructed Compojure route (e.g. `/api/card/:id`),
+ never the raw URI or query string, so entity ids and filter values never land in the table.
+
+ No free-text error column, deliberately. `mcp_tool_call_log` stores a truncated, PII-gated
+ `error_message`, but `/api/*` failures echo submitted request data far more often than MCP tool
+ calls do — validation errors quote the offending value, native-query errors quote the SQL — so an
+ error string here would drag request payloads into an analytics table behind nothing but a PII
+ toggle. `api_key_usage_log` therefore has no error column at all: the non-PII `status` column (the
+ HTTP status code) already separates success from failure, and there is nothing free-text left to
+ gate.
+
+ `client_name` is classified from the caller's self-reported `User-Agent` via [[detect-client]] —
+ analytics only, never used to gate access — mirroring `agent_api_call_log`'s `client_name`. Unlike
+ `user_agent` (raw, PII-gated), `client_name` is a canonical, low-cardinality value and is always
+ recorded.
+
+ `embedding_client` is the raw `X-Metabase-Client` header, when present — non-PII (same status as
+ `view_log`/`query_execution.embedding_client`), passed through unclassified. It's supplementary:
+ `client_name` stays the primary classification axis, since almost no API-key traffic sets this
+ header (the SDK/embed.js clients that do authenticate via JWT/SSO, not API keys).
+
+ `embedding_hostname` is the hostname parsed from the embed referrer header, when present — non-PII
+ (same status as `view_log`/`query_execution`/`metabot_conversation.embedding_hostname`), always
+ recorded. Only meaningful alongside `embedding_client`: the SDK sends an API key only on localhost,
+ so a non-localhost hostname on embedding traffic is worth flagging."
+ (:require
+ [clojure.string :as str]
+ [metabase.premium-features.core :refer [defenterprise]]
+ [metabase.util :as u]))
+
+(def supported-client-keys
+ "Canonical client keys [[detect-client]] classifies callers into for analytics. Keep in sync with
+ the `client_name` CASE in the `v_api_key_usage` view SQL (the enum-<->-CASE sync footgun)."
+ #{"metabase-cli" "curl" "postman" "python-requests" "r" "node"})
+
+(def ^:private client-name-matchers
+ "Ordered `[substring canonical-key]` pairs matched against the lowercased `User-Agent`. First match
+ wins. `r-curl` is checked before the generic `curl` so R's httr (whose User-Agent embeds `r-curl`)
+ doesn't fall through to the plain curl classification. Covers the tools/languages the public API
+ docs demonstrate, plus the Metabase CLI, which authenticates exclusively via API key."
+ [["metabase-cli" "metabase-cli"]
+ ["postmanruntime" "postman"]
+ ["python-requests" "python-requests"]
+ ["r-curl" "r"]
+ ["got (https" "node"]
+ ["curl" "curl"]])
+
+(defn detect-client
+ "Classify a caller's `User-Agent` into a canonical client key (one of [[supported-client-keys]]), or
+ `\"other\"` when nothing matches (or the header is absent). Identity is self-reported and used for
+ analytics only — never to gate access."
+ [user-agent]
+ (let [ua (some-> user-agent u/lower-case-en)]
+ (or (when ua
+ (some (fn [[needle k]] (when (str/includes? ua needle) k)) client-name-matchers))
+ "other")))
+
+(defenterprise record-api-key-usage!
+ "Record one completed API-key-authenticated request: write an `api_key_usage_log` row and stamp
+ `api_key.last_used_at`. OSS no-op."
+ metabase-enterprise.api-keys.usage
+ [_request _response _extra-info]
+ nil)
+
+(defenterprise flush-pending-writes!
+ "Synchronously flush any pending [[record-api-key-usage!]] writes instead of waiting for the
+ scheduled interval. OSS no-op."
+ metabase-enterprise.api-keys.usage
+ []
+ nil)
diff --git a/src/metabase/metabot/settings.clj b/src/metabase/metabot/settings.clj
index 00a090f8f89..5d7222b2eca 100644
--- a/src/metabase/metabot/settings.clj
+++ b/src/metabase/metabot/settings.clj
@@ -332,7 +332,7 @@
env-var-value)))
(defsetting ai-usage-max-retention-days
- (deferred-tru "Number of days to retain rows in the ai_usage_log, metabot_conversation, and metabot_message tables. Minimum value is 30; set to 0 to retain data indefinitely.")
+ (deferred-tru "Number of days to retain rows in the ai_usage_log, metabot_conversation, metabot_message, agent_api_call_log, and api_key_usage_log tables. Minimum value is 30; set to 0 to retain data indefinitely.")
:type :integer
:visibility :admin
:setter :none
@@ -346,6 +346,7 @@
- `metabot_conversation`
- `metabot_message`
- `agent_api_call_log`
+- `api_key_usage_log`
Once a day, Metabase deletes rows older than this threshold. The minimum value is 30 days (Metabase will treat entered values of 1 to 29 the same as 30).
If set to 0, Metabase will keep all rows. If you don't set this variable, Metabase keeps rows for 180 days.")
diff --git a/src/metabase/models/resolution.clj b/src/metabase/models/resolution.clj
index 55c0c20af08..c66e7bb12ca 100644
--- a/src/metabase/models/resolution.clj
+++ b/src/metabase/models/resolution.clj
@@ -17,6 +17,7 @@
:model/AnalysisFinding metabase-enterprise.dependencies.models.analysis-finding
:model/AnalysisFindingError metabase-enterprise.dependencies.models.analysis-finding-error
:model/ApiKey metabase.api-keys.models.api-key
+ :model/ApiKeyUsageLog metabase.api-keys.models.api-key-usage-log
:model/ApplicationPermissionsRevision metabase.permissions.models.application-permissions-revision
:model/AuditLog metabase.audit-app.models.audit-log
:model/AuthIdentity metabase.auth-identity.models.auth-identity
diff --git a/src/metabase/request/schema.clj b/src/metabase/request/schema.clj
index 432ba6057b6..16930312088 100644
--- a/src/metabase/request/schema.clj
+++ b/src/metabase/request/schema.clj
@@ -18,7 +18,12 @@
[:token-scopes {:optional true} [:maybe [:set [:or :keyword :string]]]]
[:token-scopes-checked {:optional true} :boolean]
[:data-app-scoped? {:optional true} :boolean]
- [:authenticated-via-oauth? {:optional true} :boolean]])
+ [:authenticated-via-oauth? {:optional true} :boolean]
+ ;; only API-key auth resolves these two: `:api-key-id` identifies the key itself (for per-key usage analytics),
+ ;; and `:api-key-creator-id` is the real human who created the key (distinct from `:metabase-user-id`, the key's
+ ;; own synthetic service-account user) — both read off the same auth query rather than looked up again later.
+ [:api-key-id {:optional true} pos-int?]
+ [:api-key-creator-id {:optional true} [:maybe pos-int?]]])
(mr/def ::multipart-file
"One `:multipart-params` entry for an uploaded file, as `ring.middleware.multipart-params` builds it."
@@ -61,6 +66,16 @@
[:route-params {:optional true} ms/RingRequestParams]
[:cookies {:optional true} [:map-of :string ::cookie-attrs]]
[:route-metadata {:optional true} [:maybe :metabase.api.macros/route-metadata]]
+ ;; accumulated by `metabase.api.util.handlers/route-map-handler` as routing descends; consumed by
+ ;; `metabase.api.macros/request-route-prefix` to reconstruct the matched route's template.
+ [:route-prefix {:optional true} [:maybe :string]]
+ ;; the reconstructed Clout pattern of the endpoint that matched, e.g. `/api/card/:id` — see
+ ;; `metabase.api.macros/route-template`.
+ [:route-template {:optional true} [:maybe :string]]
+ ;; a `volatile!` middleware running above the routing tree can install so it learns which route
+ ;; template matched, even for a response built from an exception — see
+ ;; `metabase.api.macros/route-template-carrier-key`.
+ [:metabase.api.macros/route-template-carrier {:optional true} [:maybe (ms/InstanceOfClass clojure.lang.Volatile)]]
[:compojure/path {:optional true} :string]
[:compojure/route-context {:optional true} [:maybe :string]]
[:context {:optional true} [:maybe :string]]
@@ -83,6 +98,9 @@
[:user-locale {:optional true} [:maybe :string]]
[:embedding/auth-method {:optional true} [:maybe :string]]
[:metabase/authed-session-key-hash {:optional true} [:maybe :string]]
+ ;; only API-key auth resolves these two — see `::current-user-info`.
+ [:api-key-id {:optional true} [:maybe :int]]
+ [:api-key-creator-id {:optional true} [:maybe :int]]
[:token-exchange? {:optional true} :boolean]
[:metabase.server.middleware.offset-paging/limit {:optional true} [:maybe :int]]
[:metabase.server.middleware.offset-paging/offset {:optional true} [:maybe :int]]
diff --git a/src/metabase/server/db.clj b/src/metabase/server/db.clj
index 96f3b4fd82a..af670ea81f9 100644
--- a/src/metabase/server/db.clj
+++ b/src/metabase/server/db.clj
@@ -66,7 +66,13 @@
(fn [enable-advanced-permissions?]
(first
(t2.pipeline/compile*
- (cond-> {:select [[:api_key.user_id :metabase-user-id]
+ ;; `api-key-id` and `api-key-creator-id` are here for API-key usage analytics: the auth query already has
+ ;; both rows joined, so carrying them on the request costs nothing and spares the response path a second
+ ;; lookup. `api-key-creator-id` is the real human who created the key — distinct from `metabase-user-id`,
+ ;; which is the key's own synthetic service-account user used for permission checks.
+ (cond-> {:select [[:api_key.id :api-key-id]
+ [:api_key.creator_id :api-key-creator-id]
+ [:api_key.user_id :metabase-user-id]
[:api_key.key :api-key]
[:user.is_superuser :is-superuser?]
[:user.is_data_analyst :is-data-analyst?]
@@ -132,8 +138,8 @@
(t2/query-one (cons sql params))))
(mu/defn api-key-user-info
- "The user id, api key, superuser/data-analyst/group-manager flags, and locale for the active User whose ApiKey
- starts with `key-prefix`, or nil if there is none."
+ "The API key id, user id, api key, superuser/data-analyst/group-manager flags, and locale for the active User
+ whose ApiKey starts with `key-prefix`, or nil if there is none."
[key-prefix :- :string
enable-advanced-permissions? :- :boolean]
(t2/query-one (cons (user-data-for-api-key-prefix-query enable-advanced-permissions?) [key-prefix])))
diff --git a/src/metabase/server/handler.clj b/src/metabase/server/handler.clj
index 3b0780c2eb1..c17e6b25ed0 100644
--- a/src/metabase/server/handler.clj
+++ b/src/metabase/server/handler.clj
@@ -17,6 +17,7 @@
[metabase.server.middleware.offset-paging :as mw.offset-paging]
[metabase.server.middleware.premium-features-cache :as mw.pf-cache]
[metabase.server.middleware.request-id :as mw.request-id]
+ [metabase.server.middleware.route-template-carrier :as mw.route-template-carrier]
[metabase.server.middleware.security :as mw.security]
[metabase.server.middleware.session :as mw.session]
[metabase.server.middleware.settings-cache :as mw.settings-cache]
@@ -115,6 +116,7 @@
#'wrap-gzip ; GZIP response if client can handle it
#'mw.trace/wrap-trace ; Create root OpenTelemetry span per request (after request-id is available)
#'mw.request-id/wrap-request-id ; Add a unique request ID to the request
+ #'mw.route-template-carrier/wrap-route-template-carrier ; Install a carrier so routing can report which route matched
#'mw.misc/bind-request ; bind `metabase.middleware.misc/*request*` for the duration of the request
#'mw.ssl/redirect-to-https-middleware
wrap-reload-dev-mw ; reloads outdated clojure code when --hot flag is passed with the :dev-start alias
diff --git a/src/metabase/server/middleware/log.clj b/src/metabase/server/middleware/log.clj
index 0a385e7f508..3ff57c68258 100644
--- a/src/metabase/server/middleware/log.clj
+++ b/src/metabase/server/middleware/log.clj
@@ -3,7 +3,10 @@
(:require
[clojure.core.async :as a]
[clojure.string :as str]
+ [java-time.api :as t]
+ [metabase.api-keys.usage :as api-keys.usage]
[metabase.api.common :as api]
+ [metabase.api.macros :as api.macros]
[metabase.app-db.core :as mdb]
[metabase.driver.sql-jdbc.execute.diagnostic :as sql-jdbc.execute.diagnostic]
[metabase.request.core :as request]
@@ -24,12 +27,13 @@
(set! *warn-on-reflection* true)
-;; To simplify passing large amounts of arguments around most functions in this namespace take an "info" map that
+;; To simplify passing large amounts of arguments around, the logging functions below take an "info" map that
;; looks like
;;
-;; {:request ..., :response ..., :start-time ..., :call-count-fn ...}
+;; {:request ..., :response ..., :start-time ..., :call-count-fn ..., :diag-info-fn ..., :log-context ...}
;;
-;; This map is created in `log-api-call` at the bottom of this namespace.
+;; This map is built in `log-api-call` at the bottom of this namespace, once a response exists. API-key usage
+;; recording is a separate concern with its own inputs — see [[record-api-key-usage!]] — and never touches it.
;;; +----------------------------------------------------------------------------------------------------------------+
;;; | Getting & Formatting Request/Response Info |
@@ -192,6 +196,47 @@
(log-info info)))
response)
+;;; +----------------------------------------------------------------------------------------------------------------+
+;;; | API Key Usage Analytics |
+;;; +----------------------------------------------------------------------------------------------------------------+
+
+(defn- api-key-request?
+ "Whether `request` authenticated with an API key — the only kind of request that gets recorded. Resolved well
+ outside this middleware by `metabase.server.middleware.session/wrap-current-user-info`, so it is already on the
+ request we closed over. Everything else pays this one keyword lookup and nothing more.
+
+ Checks `:api-key-id` rather than `:embedding/auth-method` — that key is stamped `agent-api`/`metabot`/`public`/
+ `guest` etc. for those routes even when the request authenticated with an API key, so matching on `\"api-key\"`
+ missed all of them. `:api-key-id` is only ever set by API-key auth, on every route."
+ [request]
+ (some? (:api-key-id request)))
+
+(defn- record-api-key-usage!
+ "Record API-key usage analytics for a completed request.
+
+ Hands the recorder the raw `request`/`response` plus the handful of values only this middleware can supply:
+ `route-template` (read off the carrier `metabase.server.middleware.route-template-carrier/wrap-route-template-carrier`
+ installed on every request — nil for a request that matched no endpoint and for raw-Compojure handlers that bypass
+ `defendpoint`, since neither ever fills it in; a dynamic binding wouldn't survive an async `respond` on another
+ thread, which is why this is a carrier and not `api/*current-route*` or similar), `duration-ms` (time to `respond`,
+ not to the last byte written — for streaming and core.async responses `respond` is called when the response object
+ is created, so this is time-to-response, as it is for the CLI usage log), and `occurred-at` (captured here on the
+ request thread rather than left for the DB to fill in at INSERT time — the row lands via a scheduled flush, up to
+ the flush interval later, so a DB-computed default would record when the flush ran, not when the request happened).
+
+ Best-effort throughout: the recorders swallow their own failures, and this catches anything else, so usage
+ analytics can never fail a request or alter its response."
+ [request response start-time]
+ (when (api-key-request? request)
+ (try
+ (api-keys.usage/record-api-key-usage!
+ request response
+ {:route-template (some-> (get request api.macros/route-template-carrier-key) deref)
+ :duration-ms (long (u/since-ms start-time))
+ :occurred-at (t/offset-date-time)})
+ (catch Throwable e
+ (log/warn e "Error recording API key usage")))))
+
;;; +----------------------------------------------------------------------------------------------------------------+
;;; | Middleware |
;;; +----------------------------------------------------------------------------------------------------------------+
@@ -215,23 +260,33 @@
(not ((logging-disabled-uris) uri))))
(defn log-api-call
- "Logs info about request such as status code, number of DB calls, and time taken to complete."
+ "Logs info about request such as status code, number of DB calls, and time taken to complete. Also the write point
+ for API-key usage analytics — see [[record-api-key-usage!]]; requests that didn't authenticate with an API key are
+ unaffected.
+
+ Console logging and API-key usage recording are independent concerns with independent eligibility: a request
+ suppressed from the console log (health checks, `/api/logger/logs`) still has its usage recorded if it
+ authenticated with an API key, and vice versa. Neither gates the other."
[handler]
(fn [request respond raise]
- (if-not (should-log-request? request)
- ;; non-API call or health or logs call, don't log it
- (handler request respond raise)
- ;; API call, log info about it
- (t2/with-call-count [call-count-fn]
- (sql-jdbc.execute.diagnostic/capturing-diagnostic-info [diag-info-fn]
- (let [info {:request request
- :start-time (u/start-timer)
- :call-count-fn call-count-fn
- :diag-info-fn diag-info-fn}
- response->info (fn [response]
- (assoc info
- :response response
- :log-context {:metabase-user-id (or (:metabase-user-id (meta response))
- api/*current-user-id*)}))
- respond (comp respond logged-response response->info)]
- (handler request respond raise)))))))
+ (let [should-log? (should-log-request? request)
+ api-key? (api-key-request? request)]
+ (if-not (or should-log? api-key?)
+ ;; neither concern applies — skip the wrapping entirely
+ (handler request respond raise)
+ (t2/with-call-count [call-count-fn]
+ (sql-jdbc.execute.diagnostic/capturing-diagnostic-info [diag-info-fn]
+ (let [start-time (u/start-timer)
+ respond* (fn [response]
+ (when api-key?
+ (record-api-key-usage! request response start-time))
+ (when should-log?
+ (logged-response {:request request
+ :response response
+ :start-time start-time
+ :call-count-fn call-count-fn
+ :diag-info-fn diag-info-fn
+ :log-context {:metabase-user-id (or (:metabase-user-id (meta response))
+ api/*current-user-id*)}}))
+ (respond response))]
+ (handler request respond* raise))))))))
diff --git a/src/metabase/server/middleware/route_template_carrier.clj b/src/metabase/server/middleware/route_template_carrier.clj
new file mode 100644
index 00000000000..0c771d38e68
--- /dev/null
+++ b/src/metabase/server/middleware/route_template_carrier.clj
@@ -0,0 +1,15 @@
+(ns metabase.server.middleware.route-template-carrier
+ (:require
+ [metabase.api.macros :as api.macros]))
+
+(defn wrap-route-template-carrier
+ "Installs a fresh `volatile!` on every request under `api.macros/route-template-carrier-key`, so
+ routing can record which route template matched (see [[api.macros/route-template-carrier-key]])
+ for any middleware to read at respond time, not just `metabase.server.middleware.log/log-api-call`
+ — which used to install this carrier itself, conditionally, only for API-key requests. Installing it
+ unconditionally here costs one `volatile!` and one `assoc` per request, and lets a middleware that
+ runs outside `log-api-call` (e.g. `metabase.server.middleware.trace/wrap-trace`, wanting the matched
+ route as a span attribute) read the same carrier without touching routing itself."
+ [handler]
+ (fn [request respond raise]
+ (handler (assoc request api.macros/route-template-carrier-key (volatile! nil)) respond raise)))
diff --git a/src/metabase/testing_api/api.clj b/src/metabase/testing_api/api.clj
index dd1dbf80932..8e06ebea365 100644
--- a/src/metabase/testing_api/api.clj
+++ b/src/metabase/testing_api/api.clj
@@ -8,6 +8,7 @@
[java-time.clock]
[medley.core :as m]
[metabase.analytics.core :as analytics]
+ [metabase.api-keys.usage :as api-keys.usage]
[metabase.api.common :as api]
[metabase.api.macros :as api.macros]
[metabase.app-db.core :as mdb]
@@ -631,3 +632,32 @@
:error-code error_code
:error-message error_message})
{:session_id session-id :tool_name tool-name}))
+
+(api.macros/defendpoint :post "/api-keys/seed-usage"
+ :- [:map [:inserted :int]]
+ "Record one completed API-key-authenticated request so the API-key usage E2E page has a visible
+ row, then force an immediate flush of the usage-log and last_used_at batches (both normally
+ flushed on a scheduled interval) so the row is queryable without waiting. Routes through the
+ production `metabase.api-keys.usage/record-api-key-usage!` path (rather than a hand-rolled insert)
+ so the seeded row can't drift from real writes. Intended only for E2E tests."
+ [_route-params
+ _query-params
+ {:keys [api_key_id user_id created_by_id route_template status duration_ms]}
+ :- [:map {:closed true}
+ [:api_key_id ms/PositiveInt]
+ [:user_id ms/PositiveInt]
+ [:created_by_id ms/PositiveInt]
+ [:route_template {:optional true} [:maybe ms/NonBlankString]]
+ [:status {:optional true} [:maybe :int]]
+ [:duration_ms {:optional true} [:maybe ms/IntGreaterThanOrEqualToZero]]]]
+ (api-keys.usage/record-api-key-usage!
+ {:api-key-id api_key_id
+ :metabase-user-id user_id
+ :api-key-creator-id created_by_id
+ :request-method :get
+ :headers {"user-agent" "curl/8.0.1"}}
+ {:status (or status 200)}
+ {:route-template (or route_template "/api/testing/api-keys/seed-usage")
+ :duration-ms (or duration_ms 42)})
+ (api-keys.usage/flush-pending-writes!)
+ {:inserted 1})
diff --git a/test/metabase/api/macros_test.clj b/test/metabase/api/macros_test.clj
index bed11aba410..165ec5afdbc 100644
--- a/test/metabase/api/macros_test.clj
+++ b/test/metabase/api/macros_test.clj
@@ -209,3 +209,17 @@
::lib.schema.parameter/parameter
{:type :string/contains, :value ["A"], :options {:case-sensitive false, :lib/uuid "not-yours"}}
{:type :string/contains, :value ["A"], :options {:case-sensitive false}})))
+
+(deftest ^:parallel route-template-test
+ (testing "the route template is the accumulated prefix plus the endpoint's declared path"
+ (are [prefix path expected] (= expected
+ (#'api.macros/route-template prefix path))
+ "/api/card" "/:id" "/api/card/:id"
+ "/api/card" "/:id/query/:export-format" "/api/card/:id/query/:export-format"
+ ;; a `"/"` endpoint is the prefix itself -- no meaningless trailing slash
+ "/api/card" "/" "/api/card"
+ ;; no prefix at all (an endpoint handler used on its own)
+ nil "/:id" "/:id"
+ "" "/:id" "/:id"
+ nil "/" "/"
+ "" "/" "/")))
diff --git a/test/metabase/api/util/handlers_test.clj b/test/metabase/api/util/handlers_test.clj
new file mode 100644
index 00000000000..670cbc53237
--- /dev/null
+++ b/test/metabase/api/util/handlers_test.clj
@@ -0,0 +1,221 @@
+(ns metabase.api.util.handlers-test
+ "Tests for route-template reconstruction: as a request descends the routing tree, each level records the route
+ pattern it consumed on the request's `:route-prefix`, and the endpoint that finally matches gets stamped with a
+ `:route-template` — the full template, e.g. `\"/api/card/:id\"`.
+
+ The endpoints below exist only to echo that `:route-template` back so tests can assert on it."
+ (:require
+ [clojure.test :refer :all]
+ [metabase.api.common :as api]
+ [metabase.api.macros :as api.macros]
+ [metabase.api.util.handlers :as handlers]
+ [metabase.initialization-status.core :as init-status]
+ [metabase.server.routes :as server.routes]
+ [metabase.test.util.dynamic-redefs :as dynamic-redefs]
+ [metabase.util :as u]))
+
+(set! *warn-on-reflection* true)
+
+;;;; ------------------------------------------------- endpoints --------------------------------------------------
+
+(defn- echo-route-template [request]
+ {:status 200
+ :body {:route-template (:route-template request)}})
+
+(api.macros/defendpoint :get "/"
+ "Root route."
+ [_route-params _query-params _body request]
+ (echo-route-template request))
+
+(api.macros/defendpoint :get "/:id"
+ "Single route param."
+ [_route-params _query-params _body request]
+ (echo-route-template request))
+
+(api.macros/defendpoint :get ["/uuid/:uuid" :uuid u/uuid-regex]
+ "Route param constrained by an explicit regex. The template must name the param, not the regex."
+ [_route-params _query-params _body request]
+ (echo-route-template request))
+
+(api.macros/defendpoint :get ["/:id/query/:export-format" :id #"[0-9]+" :export-format #"csv|json"]
+ "Several segments, two of them params."
+ [_route-params _query-params _body request]
+ (echo-route-template request))
+
+(api.macros/defendpoint :get "/:id/boom"
+ "An endpoint that throws rather than responding, the way most Metabase error responses are produced."
+ [_route-params _query-params _body _request]
+ (api/check-404 nil))
+
+(def ^:private endpoints-handler
+ (delay (api.macros/ns-handler 'metabase.api.util.handlers-test)))
+
+;;;; ------------------------------------------------ test helpers ------------------------------------------------
+
+(defn- noop-handler
+ "A no-op async Ring handler that always responds nil — used to fill the `:auth`, `:oauth`, and `:well-known` slots
+ in [[server.routes/make-routes]] when tests only care about the `/api` path."
+ [_request respond _raise]
+ (respond nil))
+
+(defn- make-test-routes
+ "Wrap an API handler in the map that [[server.routes/make-routes]] expects."
+ [api-handler]
+ (server.routes/make-routes {:api api-handler
+ :auth noop-handler
+ :oauth noop-handler
+ :well-known noop-handler}))
+
+(defn- handle
+ "Invoke the async Ring `handler` and return its response synchronously."
+ [handler request]
+ (let [result (promise)]
+ (handler request #(deliver result %) #(deliver result %))
+ (let [response (deref result 10000 ::timeout)]
+ (when (instance? Throwable response)
+ (throw response))
+ response)))
+
+(defn- route-template
+ "`GET` `uri` through `handler` and return the `:route-template` the routing machinery stamped on the request, or
+ `::no-match` if nothing matched."
+ ([handler uri]
+ (route-template handler uri nil))
+ ([handler uri extra-request-keys]
+ (->> (merge {:request-method :get, :uri uri, :headers {}} extra-request-keys)
+ (handle handler)
+ :body
+ :route-template)))
+
+(defn- api-route-template
+ "Like [[route-template]], but goes through the real top-level Metabase handler with `route-map` mounted where the
+ `/api` routes normally live — i.e. behind the `(context \"/api\" [] ...)`
+ in [[metabase.server.routes/make-routes]]. This is what proves the `/api` segment, which Compojure's `context`
+ consumes before our own routing code ever sees it, still makes it into the template."
+ ([route-map uri]
+ (api-route-template route-map uri nil))
+ ([route-map uri extra-request-keys]
+ (dynamic-redefs/with-dynamic-fn-redefs [init-status/complete? (constantly true)]
+ (route-template (make-test-routes (handlers/route-map-handler route-map))
+ uri
+ extra-request-keys))))
+
+(defn- carried-route-template
+ "`GET` `uri` through the real `/api` routing stack with a route-template carrier installed on the request the way
+ `metabase.server.middleware.log` installs one, and return what routing recorded into it. Tolerates a request that
+ ends in `raise` — that is the case this mechanism exists for."
+ [route-map uri]
+ (let [carrier (volatile! nil)
+ result (promise)]
+ (dynamic-redefs/with-dynamic-fn-redefs [init-status/complete? (constantly true)]
+ ((make-test-routes (handlers/route-map-handler route-map))
+ {:request-method :get
+ :uri uri
+ :headers {}
+ api.macros/route-template-carrier-key carrier}
+ #(deliver result %)
+ #(deliver result %)))
+ (deref result 10000 ::timeout)
+ @carrier))
+
+(def ^:private api-route-map
+ (delay {"/handlers-test" @endpoints-handler}))
+
+;;;; --------------------------------------------------- tests ----------------------------------------------------
+
+(deftest ^:parallel route-template-includes-compojure-context-test
+ (testing "the `/api` prefix consumed by Compojure's `context` is part of the template"
+ (is (= "/api/handlers-test/:id"
+ (api-route-template @api-route-map "/api/handlers-test/123")))))
+
+(deftest ^:parallel route-template-root-route-test
+ (testing "a `\"/\"` endpoint is the prefix itself, with no trailing slash"
+ (are [uri] (= "/api/handlers-test"
+ (api-route-template @api-route-map uri))
+ "/api/handlers-test"
+ "/api/handlers-test/")))
+
+(deftest ^:parallel route-template-regex-constrained-param-test
+ (testing "an explicitly regex-constrained param appears as its placeholder name, never as the regex"
+ (is (= "/api/handlers-test/uuid/:uuid"
+ (api-route-template @api-route-map "/api/handlers-test/uuid/f7e9a4b8-0000-4000-8000-abcdefabcdef")))))
+
+(deftest ^:parallel route-template-unmatched-route-test
+ (testing "nothing is stamped when no endpoint matches"
+ ;; deliberately not routed through [[api-route-template]]: an unmatched `/api/...` request falls all the way
+ ;; through to the SPA catch-all, which needs a running app.
+ (is (nil? (handle (handlers/route-map-handler @api-route-map)
+ {:request-method :get
+ :uri "/handlers-test/uuid/not-a-uuid"
+ :headers {}})))))
+
+(deftest ^:parallel route-template-multiple-params-test
+ (is (= "/api/handlers-test/:id/query/:export-format"
+ (api-route-template @api-route-map "/api/handlers-test/123/query/csv"))))
+
+(deftest ^:parallel route-template-nested-route-maps-test
+ (testing "every route-map level contributes the prefix it consumed"
+ (is (= "/api/handlers-test/nested/deeper/:id"
+ (api-route-template {"/handlers-test" {"/nested" {"/deeper" @endpoints-handler}}}
+ "/api/handlers-test/nested/deeper/123")))))
+
+(deftest ^:parallel route-template-excludes-query-string-test
+ (testing "the template is built from route structure only — nothing from the query string leaks in"
+ (are [extra] (= "/api/handlers-test/:id"
+ (api-route-template @api-route-map "/api/handlers-test/123" extra))
+ {:query-string "secret=hunter2&card_id=456"}
+ {:query-params {"secret" "hunter2", "card_id" "456"}}
+ {:query-string "secret=hunter2", :query-params {"secret" "hunter2"}})))
+
+(deftest ^:parallel route-template-outside-api-context-test
+ (testing "route maps not mounted under a Compojure context (e.g. the `/auth` routes) accumulate from the root"
+ (let [handler (handlers/route-map-handler {"/auth" {"/handlers-test" @endpoints-handler}})]
+ (is (= "/auth/handlers-test/:id"
+ (route-template handler "/auth/handlers-test/123")))
+ (is (= "/auth/handlers-test"
+ (route-template handler "/auth/handlers-test"))))))
+
+(deftest ^:parallel route-template-without-any-prefix-test
+ (testing "an endpoint handler used on its own still gets its ns-relative template"
+ (is (= "/:id"
+ (route-template @endpoints-handler "/123")))
+ (is (= "/"
+ (route-template @endpoints-handler "/")))))
+
+(deftest ^:parallel route-template-carrier-test
+ (testing "routing reports the matched template back to middleware above it through the carrier"
+ ;; routing hands the matched endpoint a *new* request map, so middleware sitting above the routing tree — which
+ ;; closed over the pre-routing request — can never see `:route-template` on it.
+ (is (= "/api/handlers-test/:id"
+ (carried-route-template @api-route-map "/api/handlers-test/123")))
+ (is (= "/api/handlers-test"
+ (carried-route-template @api-route-map "/api/handlers-test")))))
+
+(deftest ^:parallel route-template-carrier-covers-endpoints-that-throw-test
+ (testing "an endpoint that throws still reports its template — the carrier is written before the handler runs"
+ ;; this is why the template is not simply attached to the response: an exception's response is built by
+ ;; `metabase.server.middleware.exceptions/catch-api-exceptions`, not by the endpoint.
+ (is (= "/api/handlers-test/:id/boom"
+ (carried-route-template @api-route-map "/api/handlers-test/123/boom")))))
+
+(deftest ^:parallel route-template-carrier-stays-empty-when-nothing-matches-test
+ (testing "nothing is recorded when no endpoint matches"
+ ;; as in [[route-template-unmatched-route-test]], deliberately not routed through the real `/api` routes: an
+ ;; unmatched `/api/...` request falls through to the SPA catch-all, which needs a running app.
+ (let [carrier (volatile! nil)]
+ (handle (handlers/route-map-handler @api-route-map)
+ {:request-method :get
+ :uri "/handlers-test/uuid/not-a-uuid"
+ :headers {}
+ api.macros/route-template-carrier-key carrier})
+ (is (nil? @carrier)))))
+
+(deftest ^:parallel route-prefix-is-accumulated-not-overwritten-test
+ (testing "each level appends to `:route-prefix` rather than replacing it"
+ (let [prefixes (atom [])
+ spy (fn [request respond _raise]
+ (swap! prefixes conj (:route-prefix request))
+ (respond {:status 200, :body {}}))
+ handler (handlers/route-map-handler {"/a" {"/b" {"/c" spy}}})]
+ (handle handler {:request-method :get, :uri "/a/b/c/d", :headers {}})
+ (is (= ["/a/b/c"] @prefixes)))))
diff --git a/test/metabase/api_keys/api_test.clj b/test/metabase/api_keys/api_test.clj
index bd3355731e8..b5d3ffdb972 100644
--- a/test/metabase/api_keys/api_test.clj
+++ b/test/metabase/api_keys/api_test.clj
@@ -19,7 +19,7 @@
resp (mt/user-http-request :crowberto :post 200 "api-key"
{:group_id group-id
:name name})]
- (is (= #{:name :group :unmasked_key :masked_key :id :created_at :updated_at :updated_by}
+ (is (= #{:name :group :unmasked_key :masked_key :id :created_at :updated_at :updated_by :last_used_at}
(-> resp keys set)))
(is (= (select-keys (mt/fetch-user :crowberto) [:id :common_name])
(:updated_by resp)))
@@ -31,7 +31,7 @@
(testing "Trying to create another API key with the same name fails"
(let [key-name (str (random-uuid))]
;; works once...
- (is (= #{:unmasked_key :masked_key :group :name :id :created_at :updated_at :updated_by}
+ (is (= #{:unmasked_key :masked_key :group :name :id :created_at :updated_at :updated_by :last_used_at}
(set (keys (mt/user-http-request :crowberto :post 200 "api-key"
{:group_id group-id
:name key-name})))))
@@ -204,7 +204,7 @@
{:name name-2})
(is (= name-2 (:common_name (t2/select-one :model/User api-user-id)))))
(testing "the shape of the response is correct"
- (is (= #{:created_at :updated_at :updated_by :id :group :name :masked_key}
+ (is (= #{:created_at :updated_at :updated_by :id :group :name :masked_key :last_used_at}
(set (keys (mt/user-http-request :crowberto :put 200 (str "api-key/" id)
{:name name-1}))))))))))
diff --git a/test/metabase/api_keys/db_test.clj b/test/metabase/api_keys/db_test.clj
new file mode 100644
index 00000000000..e5713827069
--- /dev/null
+++ b/test/metabase/api_keys/db_test.clj
@@ -0,0 +1,53 @@
+(ns metabase.api-keys.db-test
+ (:require
+ [clojure.test :refer [deftest is testing]]
+ [java-time.api :as t]
+ [metabase.api-keys.core :as-alias api-keys]
+ [metabase.api-keys.db :as api-keys.db]
+ [metabase.test :as mt]
+ [toucan2.core :as t2]))
+
+(defn- last-used-at [api-key-id]
+ (t2/select-one-fn :last_used_at :model/ApiKey :id api-key-id))
+
+(defn- temp-key-opts []
+ {::api-keys/unhashed-key (str "mb_" (mt/random-name))
+ :name (mt/random-name)
+ :user_id (mt/user->id :crowberto)
+ :creator_id (mt/user->id :crowberto)
+ :updated_by_id (mt/user->id :crowberto)})
+
+(defn- now
+ "Truncated to microseconds to match real DB storage precision; H2 alone preserves nanoseconds."
+ []
+ (-> (t/instant) (t/truncate-to :micros) (t/offset-date-time (t/zone-offset 0))))
+
+(deftest update-api-keys-last-used-at!-updates-available-keys-test
+ (testing "nothing is skipped, and every key updates, when nothing else holds the rows"
+ (mt/with-temp [:model/ApiKey {id-1 :id} (temp-key-opts)
+ :model/ApiKey {id-2 :id} (temp-key-opts)]
+ (let [ts (now)
+ skipped (api-keys.db/update-api-keys-last-used-at! {id-1 ts, id-2 ts})]
+ (is (= {} skipped))
+ (is (= ts (last-used-at id-1)))
+ (is (= ts (last-used-at id-2)))))))
+
+(deftest update-api-keys-last-used-at!-skips-busy-keys-test
+ (testing "a key the lock step excludes is skipped and returned to the caller; unrelated keys still update"
+ (mt/with-temp [:model/ApiKey {available :id} (temp-key-opts)
+ :model/ApiKey {busy :id} (temp-key-opts)]
+ (let [ts (now)]
+ (mt/with-dynamic-fn-redefs [api-keys.db/lock-available-key-ids (fn [ids] (remove #{busy} ids))]
+ (let [skipped (api-keys.db/update-api-keys-last-used-at! {available ts, busy ts})]
+ (is (= {busy ts} skipped))
+ (is (= ts (last-used-at available)))
+ (is (nil? (last-used-at busy)))))))))
+
+(deftest update-api-keys-last-used-at!-drops-deleted-keys-test
+ (testing "an id the lock step excludes because the key was deleted is dropped, not retried"
+ (mt/with-temp [:model/ApiKey {available :id} (temp-key-opts)]
+ (let [ts (now)
+ deleted-id Integer/MAX_VALUE
+ skipped (api-keys.db/update-api-keys-last-used-at! {available ts, deleted-id ts})]
+ (is (= {} skipped) "the deleted id is dropped, not carried forward for another retry")
+ (is (= ts (last-used-at available)))))))
diff --git a/test/metabase/api_keys/usage_test.clj b/test/metabase/api_keys/usage_test.clj
new file mode 100644
index 00000000000..b7f393b41cc
--- /dev/null
+++ b/test/metabase/api_keys/usage_test.clj
@@ -0,0 +1,23 @@
+(ns metabase.api-keys.usage-test
+ (:require
+ [clojure.test :refer :all]
+ [metabase.api-keys.usage :as api-keys.usage]))
+
+(deftest detect-client-test
+ (testing "known clients are classified from their User-Agent"
+ (are [user-agent expected] (= expected (api-keys.usage/detect-client user-agent))
+ "metabase-cli/1.2.3" "metabase-cli"
+ "curl/8.4.0" "curl"
+ "PostmanRuntime/7.36.0" "postman"
+ "python-requests/2.31.0" "python-requests"
+ "libcurl/8.0.1 r-curl/5.1.0 httr/1.4.7" "r"
+ "got (https://github.com/sindresorhus/got)" "node"))
+ (testing "an unrecognized or absent User-Agent is \"other\""
+ (are [user-agent] (= "other" (api-keys.usage/detect-client user-agent))
+ "Mozilla/5.0 (some browser)"
+ ""
+ nil))
+ (testing "matching is case-insensitive"
+ (is (= "curl" (api-keys.usage/detect-client "CURL/8.4.0"))))
+ (testing "r-curl is classified as r, not curl, despite containing \"curl\""
+ (is (= "r" (api-keys.usage/detect-client "r-curl/5.1.0")))))
diff --git a/test/metabase/cmd/copy_test.clj b/test/metabase/cmd/copy_test.clj
index 7c7f0cec9fb..9eb39099f0f 100644
--- a/test/metabase/cmd/copy_test.clj
+++ b/test/metabase/cmd/copy_test.clj
@@ -82,6 +82,7 @@
:model/AnalysisFinding
:model/AnalysisFindingError
:model/ApiKey
+ :model/ApiKeyUsageLog
:model/CacheConfig
:model/CardFavorite
:model/CloudMigration
diff --git a/test/metabase/server/middleware/log_test.clj b/test/metabase/server/middleware/log_test.clj
index 314eab1ddd4..3cbcedfe506 100644
--- a/test/metabase/server/middleware/log_test.clj
+++ b/test/metabase/server/middleware/log_test.clj
@@ -1,7 +1,10 @@
(ns metabase.server.middleware.log-test
(:require
[clojure.test :refer :all]
+ [metabase.api-keys.usage :as api-keys.usage]
+ [metabase.api.macros :as api.macros]
[metabase.server.middleware.log :as mw.log]
+ [metabase.server.middleware.route-template-carrier :as mw.route-template-carrier]
[metabase.test :as mt]
[metabase.test.fixtures :as fixtures]))
@@ -33,6 +36,114 @@
(is (not (#'mw.log/should-log-request? {:uri "/livez"})))
(is (not (#'mw.log/should-log-request? {:uri "/readyz"}))))))
+;;; ------------------------------------------- API key usage analytics -------------------------------------------
+
+(def ^:private api-key-request
+ {:request-method :get
+ :uri "/api/card/1"
+ :headers {"user-agent" "metabase-cli/1.2.3", "x-metabase-client" "embedding-sdk-react"
+ "x-metabase-embed-referrer" "https://example.com/app"}
+ :remote-addr "203.0.113.7"
+ :embedding/auth-method "api-key"
+ :api-key-id 7
+ :metabase-user-id 3})
+
+(defn- run-log-api-call!
+ "Send `request` through [[mw.route-template-carrier/wrap-route-template-carrier]] wrapping
+ [[mw.log/log-api-call]] — mirroring their order in the real middleware stack — with a downstream
+ handler that stands in for routing — recording `route-template` into the carrier the outer
+ middleware installed, the way `metabase.api.macros` does — and then responds with `response`.
+ Returns what the API-key usage recorder was called with (`::not-called` if it wasn't) plus the
+ final response.
+
+ The recorder now takes the raw `request`/`response` plus a small `extra-info` map — see
+ `metabase-enterprise.api-keys.usage/record-api-key-usage!`. Header/field extraction from `request` is the
+ recorder's job, not this middleware's, so it's exercised in `metabase-enterprise.api-keys.usage-test`, not here."
+ [request route-template response]
+ (let [recorded (atom ::not-called)
+ final-response (atom ::no-response)
+ handler (fn [request respond _raise]
+ (some-> (get request api.macros/route-template-carrier-key)
+ (vreset! route-template))
+ (respond response))]
+ (mt/with-dynamic-fn-redefs [api-keys.usage/record-api-key-usage!
+ (fn [request response extra-info]
+ (reset! recorded {:request request, :response response, :extra-info extra-info}))]
+ ((mw.route-template-carrier/wrap-route-template-carrier (mw.log/log-api-call handler))
+ request
+ #(reset! final-response %)
+ identity))
+ {:recorded @recorded, :response @final-response}))
+
+(deftest log-api-call-records-api-key-usage-test
+ (testing "an API-key-authenticated request records one usage event"
+ (let [{:keys [recorded]}
+ (run-log-api-call! api-key-request "/api/card/:id" {:status 200, :body "ok"})]
+ (testing "the raw request and response are forwarded unchanged"
+ (is (=? api-key-request (:request recorded)))
+ (is (= {:status 200, :body "ok"} (:response recorded))))
+ (testing "extra-info carries only what the middleware alone can supply"
+ (is (= "/api/card/:id" (:route-template (:extra-info recorded))))
+ (is (int? (:duration-ms (:extra-info recorded))))
+ (is (instance? java.time.OffsetDateTime (:occurred-at (:extra-info recorded))))
+ (is (= #{:route-template :duration-ms :occurred-at}
+ (set (keys (:extra-info recorded)))))))))
+
+(deftest log-api-call-records-api-key-usage-even-when-console-logging-is-suppressed-test
+ (testing "usage recording and console-log suppression are independent eligibility checks"
+ (let [{:keys [recorded response]}
+ (run-log-api-call! (assoc api-key-request :uri "/api/logger/logs")
+ "/api/logger/logs" {:status 200, :body "ok"})]
+ (testing "/api/logger/logs is always excluded from the console log, but usage still recorded"
+ (is (not= ::not-called recorded))
+ (is (= "/api/logger/logs" (:route-template (:extra-info recorded)))))
+ (testing "the response passes through unaffected"
+ (is (= {:status 200, :body "ok"} response))))))
+
+(deftest log-api-call-records-nothing-for-other-auth-methods-test
+ (testing "session-authenticated requests are untouched"
+ (let [{:keys [recorded]}
+ (run-log-api-call! (-> api-key-request
+ (assoc :embedding/auth-method "session")
+ (dissoc :api-key-id))
+ "/api/card/:id" {:status 200, :body "ok"})]
+ (is (= ::not-called recorded))))
+ (testing "so are unauthenticated ones"
+ (let [{:keys [recorded]}
+ (run-log-api-call! (dissoc api-key-request :embedding/auth-method :api-key-id)
+ nil {:status 401, :body "Unauthenticated"})]
+ (is (= ::not-called recorded)))))
+
+(deftest log-api-call-records-api-key-usage-on-embedding-and-agent-routes-test
+ (testing "an API-key-authenticated request still records usage when the route stamps a different
+ embedding/auth-method (agent-api, metabot, public, guest — #EMB-2154 feedback)"
+ (doseq [embedding-auth-method ["agent-api" "metabot" "public" "guest"]]
+ (let [{:keys [recorded]}
+ (run-log-api-call! (assoc api-key-request :embedding/auth-method embedding-auth-method)
+ "/api/card/:id" {:status 200, :body "ok"})]
+ (is (not= ::not-called recorded) (str "auth-method " embedding-auth-method))))))
+
+(deftest log-api-call-records-api-key-usage-without-a-route-template-test
+ (testing "a request that matched no endpoint still records the event, with a nil route-template. Whether the
+ usage-log row gets dropped downstream because route_template is NOT NULL, and whether last_used_at
+ still gets stamped regardless, are decisions the recorder makes — see
+ metabase-enterprise.api-keys.usage-test."
+ (let [{:keys [recorded]}
+ (run-log-api-call! api-key-request nil {:status 404, :body "Not found."})]
+ (is (= 7 (:api-key-id (:request recorded))))
+ (is (nil? (:route-template (:extra-info recorded))))
+ (is (= 404 (:status (:response recorded)))))))
+
+(deftest log-api-call-api-key-usage-is-best-effort-test
+ (testing "a recorder that throws never breaks the response"
+ (mt/with-dynamic-fn-redefs [api-keys.usage/record-api-key-usage! (fn [& _] (throw (ex-info "boom" {})))]
+ (let [response (atom ::no-response)]
+ ((mw.log/log-api-call (fn [_request respond _raise] (respond {:status 200, :body "ok"})))
+ api-key-request
+ #(reset! response %)
+ identity)
+ (is (= {:status 200, :body "ok"} @response))))))
+
(deftest log-api-call-captures-user-id-from-response-metadata-test
(testing "log-api-call reads :metabase-user-id from response metadata (#74017)"
(let [logged-user-id (promise)
diff --git a/test/metabase/server/middleware/route_template_carrier_test.clj b/test/metabase/server/middleware/route_template_carrier_test.clj
new file mode 100644
index 00000000000..09b6880904a
--- /dev/null
+++ b/test/metabase/server/middleware/route_template_carrier_test.clj
@@ -0,0 +1,28 @@
+(ns metabase.server.middleware.route-template-carrier-test
+ (:require
+ [clojure.test :refer :all]
+ [metabase.api.macros :as api.macros]
+ [metabase.server.middleware.route-template-carrier :as mw.route-template-carrier]))
+
+(deftest wrap-route-template-carrier-installs-a-fresh-volatile-test
+ (testing "every request gets its own carrier, regardless of auth method"
+ (doseq [request [{} {:embedding/auth-method "api-key"} {:embedding/auth-method "session"}]]
+ (let [seen (atom ::not-called)]
+ ((mw.route-template-carrier/wrap-route-template-carrier
+ (fn [request respond _raise]
+ (reset! seen (get request api.macros/route-template-carrier-key))
+ (respond {:status 200})))
+ request identity identity)
+ (is (instance? clojure.lang.Volatile @seen))
+ (is (nil? (deref @seen)))))))
+
+(deftest wrap-route-template-carrier-readable-downstream-test
+ (testing "a value routing records into the carrier is visible after the inner handler returns"
+ (let [carrier (atom nil)]
+ ((mw.route-template-carrier/wrap-route-template-carrier
+ (fn [request respond _raise]
+ (vreset! (get request api.macros/route-template-carrier-key) "/api/card/:id")
+ (reset! carrier (get request api.macros/route-template-carrier-key))
+ (respond {:status 200})))
+ {} identity identity)
+ (is (= "/api/card/:id" (deref @carrier))))))
diff --git a/test/metabase/server/middleware/session_test.clj b/test/metabase/server/middleware/session_test.clj
index 91d8792e29e..0cfaa78c75a 100644
--- a/test/metabase/server/middleware/session_test.clj
+++ b/test/metabase/server/middleware/session_test.clj
@@ -250,16 +250,21 @@
(is (nil? (:metabase-user-id request'))))))
(deftest current-user-info-for-api-key-test
- (mt/with-temp [:model/ApiKey _ {:name "An API Key"
- :user_id (mt/user->id :lucky)
- :creator_id (mt/user->id :lucky)
- :updated_by_id (mt/user->id :lucky)
- ::api-key/unhashed-key (u.secret/secret "mb_foobar123")}]
+ (mt/with-temp [:model/ApiKey {api-key-id :id} {:name "An API Key"
+ :user_id (mt/user->id :lucky)
+ :creator_id (mt/user->id :lucky)
+ :updated_by_id (mt/user->id :lucky)
+ ::api-key/unhashed-key (u.secret/secret "mb_foobar123")}]
(testing "A valid API key works, and user info is added to the request"
+ ;; `:api-key-id` and `:api-key-creator-id` are resolved for API-key auth only — the usage
+ ;; analytics hook in `metabase.server.middleware.log` reads both off the request rather than
+ ;; looking them up again.
(let [req {:headers {"x-api-key" "mb_foobar123"}}]
(testing "No premium features, do not include :is-group-manager?"
(mt/with-premium-features #{}
- (is (= (merge req {:metabase-user-id (mt/user->id :lucky)
+ (is (= (merge req {:api-key-id api-key-id
+ :api-key-creator-id (mt/user->id :lucky)
+ :metabase-user-id (mt/user->id :lucky)
:is-superuser? false
:is-data-analyst? false
:user-locale nil
@@ -268,7 +273,9 @@
(testing "Include :is-group-manager? if we have EE + :advanced-permissions "
(when config/ee-available?
(mt/with-premium-features #{:advanced-permissions}
- (is (= (merge req {:metabase-user-id (mt/user->id :lucky)
+ (is (= (merge req {:api-key-id api-key-id
+ :api-key-creator-id (mt/user->id :lucky)
+ :metabase-user-id (mt/user->id :lucky)
:is-superuser? false
:is-data-analyst? false
:is-group-manager? false