User Activity API

The User Activity API allows a Google Analytics property owner to retrieve all
analytics measurement data associated with a single user. Specifically, the
API retrieves all of the measurement data associated with a particular User ID
or Client ID.

Note: See the
User-ID reference for a
brief introduction to Client IDs, User IDs, and the differences between them.

Making a User Activity Request

To make a User Activity Request, construct a request object with the following
fields:

Sessions and Activities

User activity data is grouped by session. Each
session contains general
information about the session, such as session ID and date, as well as a list
of user activities for that session.
The user activities in a session consist
of every "hit" for which the user was responsible; this includes things like
pageviews, ecommerce events, and custom events sent via gtag(...) or ga(...).

Note: Sessions cannot span date boundaries. If a user's time on your site
encompasses two different days, this will appear as two different sessions, on
different dates. For more information about how a session is defined in
Google Analytics, see
How a web session is defined in AnalyticsNote: the Activity reference contains
a more precise definition of an Activity, and the subtle ways it is distinct
from a Hit or an Event.

Pagination

The User Activity API uses pagination to break up large data sets into multiple
requests and responses. However, because the data returned by the API is
structured hierarchically, some special considerations need to be taken by the
developer in order to correctly collate the data.

The basic "row" type for the purpose of pagination is the Activity. Because User
Data is grouped by session, this means that a page boundary can occur inside of
a session, and that session can have can have activities spanning multiple pages.

Key Point: Page boundaries can occur inside a session.

Sample Data

For demonstration purposes, we'll use the following sample data. In this
example, the user interacted with the site in 6 sessions over the course of 3
days.

Date

Session ID

Event Label

Time

2018-11-23

1

A

10:26

2018-11-23

1

B

10:32

2018-11-23

1

C

10:39

2018-11-23

2

A

18:04

2018-11-23

2

B

18:11

2018-11-23

2

C

18:26

2018-11-24

3

A

11:26

2018-11-24

3

B

11:29

2018-11-24

3

C

11:39

2018-11-24

3

D

11:42

2018-11-24

4

A

23:50

2018-11-24

4

B

23:54

2018-11-25

5

C

00:02

2018-11-25

5

D

00:13

2018-11-25

6

A

13:01

2018-11-25

6

B

13:09

2018-11-25

6

C

13:12

2018-11-25

6

D

13:23

Single Page

If you make a user activity request with a pageSize of at least 18, the data
will all be delivered in a single page, and will look something like this:

Note: many fields have been omitted for brevity; this example is only meant to
show the heirarchical grouping of activities and sessions.

Multiple Pages

However, if your page size is 5, then this data will be broken up into 4
response pages:

Date

Session ID

Event Label

Time

Page 1:

2018-11-23

1

A

10:26

2018-11-23

1

B

10:32

2018-11-23

1

C

10:39

2018-11-23

2

A

18:04

2018-11-23

2

B

18:11

Page 2:

2018-11-23

2

C

18:26

2018-11-24

3

A

11:26

2018-11-24

3

B

11:29

2018-11-24

3

C

11:39

2018-11-24

3

D

11:42

Page 3:

2018-11-24

4

A

23:50

2018-11-24

4

B

23:54

2018-11-25

5

C

00:02

2018-11-25

5

D

00:13

2018-11-25

6

A

13:01

Page 4:

2018-11-25

6

B

13:09

2018-11-25

6

C

13:12

2018-11-25

6

D

13:23

Note: The user activities are always in a sorted order, which means the boundary
between pages will never be random; it will always be between temporally
adjacent sessions and activities.

Notice that session 2 is broken up across the first and second pages, and that
the 2 sessions on November 24 are broken up across the second and third pages.
The responses will look something like this:

Data Sampling

If a client has accumulated a huge amount of data for the requested date
range, the API may return only a sampled subset of activities. When this
happens, the sampleRate field will indicate what fraction of the user's
activities were returned.

How data is sampled

The user data is sampled at the activity level. For instance, with a sampling
rate of 50% (0.5), half of the user's activities will be present in the
response.

These sampled activities are selected arbitrarily; the API does not provide any
guarantees about random sampling, nor that the sampling is proportional across
activities for the given date range.

Prevent data sampling

Because this API treats a session as simply a collection of activities,
any sessions for which no activities appear in the sampled set will not appear
in the response. If you require a comprehensive list of sessions or activities,
make follow-up requests with smaller date ranges.

For example, if you request data from 2018-01-01 to 2018-12-31, and the
response indicates a sampling rate of 0.25, divide the requested date range
into 4 parts, such that each part will hopefully contain about a quarter of the
original data:

2018-01-01 to 2018-03-31

2018-04-01 to 2018-06-30

2018-07-01 to 2018-09-30

2018-10-01 to 2018-12-31

Note: Because of possible random data clustering, these subranges might
also be sampled. For instance, if most of the user's data occurred in the
2018-01-01 to 2018-03-31 date range, you may have to perform additional
requests until you have all of the unsampled data.