Method: projects.locations.datasets.appendEvents

Append events to a LOADED DataSet.

HTTP request


The URL uses gRPC Transcoding syntax.

Path parameters



Required. The DataSet to which we want to append to in the format of "projects/{project}/locations/{location}/datasets/{dataset}"

Request body

The request body contains data with the following structure:

JSON representation
  "events": [
      object (Event)

object (Event)

Events to be appended.


  1. The DataSet must be shown in a LOADED state in the results of list method; otherwise, all events from the append request will be dropped, and a NOT_FOUND status will be returned.
  2. All events in a single request must have the same groupId if set; otherwise, an INVALID_ARGUMENT status will be returned.
  3. If groupId is not set (or 0), there should be only 1 event; otherwise, an INVALID_ARGUMENT status will be returned.
  4. The events must be newer than the current time minus DataSet TTL or they will be dropped.

Response body

Response for an appendEvents RPC.

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

JSON representation
  "droppedEvents": [
      object (Event)

object (Event)

Dropped events; empty if all events are successfully added.

Authorization scopes

Requires the following OAuth scope:


For more information, see the Authentication Overview.

IAM Permissions

Requires the following IAM permission on the dataset resource:

  • timeseriesinsights.datasets.update

For more information, see the IAM documentation.


Represents an entry in a data source.

Each Event has:

  • A timestamp at which the event occurs.
  • One or multiple dimensions.
  • Optionally, an opaque group ID that allows clients to group logically related events (for example, all events representing payment transactions done by a user in a day can be assigned the same group ID). A group ID can be considered a generalization of a session ID. All events with the same group id are in the same group, and event slicing is applied to the groups. If a group ID is not provided, an internal one will be generated based on the content and eventTime, and each event is a group by itself.


  • Internally, we discretize time in equal-sized chunks and we assume an event has a 0 TimeseriesPoint.value in a chunk that does not contain any occurrences of an event in the input.
  • The number of Events with the same group ID should be limited.
  • Group ID cannot be queried.
  • Group ID does not correspond to a user ID or the like. If a user ID is of interest to be queried, use a user ID dimension instead.
JSON representation
  "dimensions": [
      object (EventDimension)
  "groupId": string,
  "eventTime": string

object (EventDimension)

Event dimensions.


string (int64 format)

Event group ID.

NOTE: JSON encoding should use a string to hold a 64-bit integer value, because a native JSON number holds only 53 binary bits for an integer.


string (Timestamp format)

Event timestamp.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".


Represents an event dimension.

JSON representation
  "name": string,

  // Union field value can be only one of the following:
  "stringVal": string,
  "longVal": string,
  "boolVal": boolean,
  "doubleVal": number
  // End of list of possible types for union field value.


Dimension name.

NOTE: EventDimension names must be composed of alphanumeric characters only, and are case insensitive. Unicode characters are not supported. The underscore '_' is also allowed.

Union field value. Dimension value.

NOTE: All entries of the dimension name must have the same value type. Violating this assumption will cause such dimensions dropped. value can be only one of the following:



String representation.

NOTE: String values are case insensitive. Unicode characters are supported.


string (int64 format)

Long representation.



Bool representation.



Double representation.