Add content_guid filtering to get_usage()

NEWS.md

@@ -1,5 +1,7 @@
 # connectapi (development version)
 
+- `get_usage()` now allows for filtering by content GUID with the `content_guid` 
+  argument. This is only available on Connect server versions 2026.01 and later. 
 - The `activate` argument to `set_schedule_*()` functions is deprecated and
   no longer has any effect, due to changes in the Connect API. It will be
   removed in a future release. (#500)

R/get.R

@@ -537,6 +537,9 @@ get_usage_static <- function(
 #' If no date-times are provided, all usage data will be returned.
 #'
 #' @param client A `Connect` R6 client object.
+#' @param content_guid Optional. A single content GUID or a character vector of
+#'   GUIDs to filter results. When multiple GUIDs are provided they are
+#'   collapsed with `"|"`.
 #' @param from Optional date-time (`POSIXct` or `POSIXlt`). Only
 #'   records after this time are returned. If not provided, records
 #'   are returned back to the first record available.
@@ -594,6 +597,9 @@ get_usage_static <- function(
 #'   from = as.POSIXct("2025-05-02 12:40:00", tz = "UTC")
 #' )
 #'
+#' # Fetch usage for a specific content item
+#' usage <- get_usage(client, content_guid = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee")
+#'
 #' # Fetch all usage
 #' usage <- get_usage(client)
 #'
@@ -605,12 +611,20 @@ get_usage_static <- function(
 #' }
 #'
 #' @export
-get_usage <- function(client, from = NULL, to = NULL) {
+get_usage <- function(client, content_guid = NULL, from = NULL, to = NULL) {
   error_if_less_than(client$version, "2025.04.0")
 
+  if (!is.null(content_guid)) {
+    error_if_less_than(client$version, "2026.01.0")
+    if (length(content_guid) > 1) {
+      content_guid <- paste0(content_guid, collapse = "|")
+    }
+  }
+
   usage <- client$GET(
     v1_url("instrumentation", "content", "hits"),
     query = list(
+      content_guid = content_guid,
       from = make_timestamp(from),
       to = make_timestamp(to)
     )

tests/testthat/2026.01.0/__api__/server_settings.json

@@ -0,0 +1,3 @@
+{
+    "version": "2026.01.0"
+}

tests/testthat/2026.01.0/__ping__.json

@@ -0,0 +1,3 @@
+{
+
+}

tests/testthat/test-get.R

@@ -469,3 +469,38 @@ with_mock_dir("2025.04.0", {
     })
   })
 })
+
+with_mock_dir("2026.01.0", {
+  test_that("content_guid is passed to the hits endpoint", {
+    client <- Connect$new(server = "https://connect.example", api_key = "fake")
+    # $version is loaded lazily, we need it before calling get_usage()
+    client$version
+
+    without_internet({
+      expect_GET(
+        get_usage(
+          client,
+          content_guid = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
+        ),
+        paste0(
+          "https://connect.example/__api__/v1/instrumentation/content/hits?",
+          "content_guid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
+        )
+      )
+      expect_GET(
+        get_usage(
+          client,
+          content_guid = c(
+            "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+            "ffffffff-1111-2222-3333-444444444444"
+          )
+        ),
+        paste0(
+          "https://connect.example/__api__/v1/instrumentation/content/hits?",
+          "content_guid=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+          "%7Cffffffff-1111-2222-3333-444444444444"
+        )
+      )
+    })
+  })
+})