Managing user events

This page describes how to import, view, update, and delete user events. For information about recording user events as they happen, see Recording user events.

Importing user events

When you want to create a new model, or recommendation, that model requires sufficient user event data for training. The amount of data required for training depends on the recommendation type and the optimization objective. It can take a considerable amount of time to collect sufficient user event data; you can accelerate this process by importing user event data from past events. You can import your user events from Cloud Storage, or insert your data inline in your request.

See User event data requirements for the required amount of training data.

In addition, review the best practices for recording user events.

Importing user events from Cloud Storage

To import user events from Cloud Storage, you create a file containing JSON data. Your JSON file should follow the formats shown in User events, depending on the user event type. Do not include the line breaks; provide an entire user event on a single line. Each user event should be on its own line.

Importing user events inline


You import user events inline by including the data for the events in your call to the eventStores.userEvents.import method.

The easiest way to do this is to put your user event data into a file and provide the file to cURL.

For the formats of the user event types, see User events.

  1. Create the .json file:

    "inputConfig": {
      "userEventInlineSource": {
          "userEvents": [
  2. Call the POST method:

    curl -X POST \
         -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
         -H "Content-Type: application/json; charset=utf-8" \
         --data @./data.json \

Listing user events

You can list user events that you have previously recorded. You use a filter string to specify which user events you want returned.


This example lists user events with a type of purchase-complete for a specific time period that are missing corresponding catalog items.

curl -X GET
    -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \

The decoded filter string looks like this:

    eventTime > "2018-04-23T18:25:43.511Z"
    eventTime < "2019-02-12T18:30:43.511Z"

Removing user events

Generally, you should leave user events in place after they have been recorded. However, if you have user events that were not recorded properly, you can remove them from your event store using the eventStores.userEvents.purge method.

Specify the events you want to remove by using a filter string. This supports selectively deleting user events by filtering on the eventTime, eventType, visitorID, and userID fields.

Because you cannot undo the delete, test your filter string by using it to list events before using it to delete them. The force field is set to false by default; this setting will return the list of events without deleting them. When you are ready to actually delete the user events, set the force field to true.


This example filters for a time range, which must use the Zulu Time date format.

Setting the force field to true forces the delete to occur. To view the list of events instead of deleting them, set force to false.

curl -X POST -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
      -H "Content-Type: application/json; charset=utf-8" \
     --data '{
              "filter":"eventTime > \"2019-12-23T18:25:43.511Z\" eventTime < \"2019-12-23T18:30:43.511Z\"",
    }' \

Viewing aggregated user event information

You can view the number of recorded user events for your project in the Event tab on the Recommendations AI Data page. Metrics will appear about 24 hours after you first upload events to Recommendations AI.

Recommendations AI User Event Stats

Using the user event filter

You can filter the results for listing user events.

The filter is a string that contains one or more of the following restrictions:

  • eventTime

    Provides a timestamp to bound the events listed or deleted. This filter can be specified once or twice, with a greater-than (>) or less-than (<) symbol. The bounded time must be a single, contiguous block.

  • eventType

    Restrict the events listed or deleted to a single event type.

  • eventsMissingCatalogItems

    By default, only events for which a catalog item was found are listed or deleted. If you specify this flag, only events for which a catalog item was not found are listed or deleted.

  • visitorID

    Restrict the events listed or deleted to a single visitor ID.

  • userID

    Restrict the events listed or deleted to a single user ID.

Only items that satisfy all of the restrictions are listed or deleted.

To list all user events of type add-to-cart that were logged on or after February 1, 2019, you would provide the following filter string:

eventTime > "2019-02-01T00:00:00Z" eventType = add-to-cart

To list all user events with catalog items that are not found in the catalog (unjoined events), you would provide the following filter string: