Method: projects.locations.catalogs.eventStores.userEvents.list

Gets a list of user events within a time range, with potential filtering. The method does not list unjoined user events.

Unjoined user event definition: when a user event is ingested from Recommendations AI User Event APIs, the catalog item included in the user event is connected with the current catalog. If a catalog item of the ingested event is not in the current catalog, it could lead to degraded model quality. This is called an unjoined event.

HTTP request


The URL uses gRPC Transcoding syntax.

Path parameters



Required. The parent eventStore resource name, such as projects/*/locations/*/catalogs/default_catalog/eventStores/default_event_store.

Authorization requires the following IAM permission on the specified resource parent:


Query parameters



Optional. Maximum number of results to return per page. If zero, the service will choose a reasonable default.



Optional. The previous ListUserEventsResponse.next_page_token.



Optional. Filtering expression to specify restrictions over returned events. This is a sequence of terms, where each term applies some kind of a restriction to the returned user events. Use this expression to restrict results to a specific time range, or filter events by eventType. eg: eventTime > "2012-04-23T18:25:43.511Z" eventsMissingCatalogItems eventTime<"2012-04-23T18:25:43.511Z" eventType=search

We expect only 3 types of fields:

  • eventTime: this can be specified a maximum of 2 times, once with a less than operator and once with a greater than operator. The eventTime restrict should result in one contiguous valid eventTime range.

  • eventType: only 1 eventType restriction can be specified.

  • eventsMissingCatalogItems: specififying this will restrict results to events for which catalog items were not found in the catalog. The default behavior is to return only those events for which catalog items were found.

Some examples of valid filters expressions:

  • Example 1: eventTime > "2012-04-23T18:25:43.511Z" eventTime < "2012-04-23T18:30:43.511Z"
  • Example 2: eventTime > "2012-04-23T18:25:43.511Z" eventType = detail-page-view
  • Example 3: eventsMissingCatalogItems eventType = search eventTime < "2018-04-23T18:30:43.511Z"
  • Example 4: eventTime > "2012-04-23T18:25:43.511Z"
  • Example 5: eventType = search
  • Example 6: eventsMissingCatalogItems

Request body

The request body must be empty.

Response body

If successful, the response body contains data with the following structure:

Response message for userEvents.list method.

JSON representation
  "userEvents": [
      object (UserEvent)
  "nextPageToken": string

object (UserEvent)

The user events.



If empty, the list is complete. If nonempty, the token to pass to the next request's userEvents.list.page_token.

Authorization Scopes

Requires the following OAuth scope:


For more information, see the Authentication Overview.