Audience List Fundamentals

Audiences in Google Analytics 4 allow you to segment your users in the ways that are important to your business. With audiences, you can group users of your site and/or application based on shared attributes.

Using the Google Analytics Data API v1 you can generate Audiences Lists, which include a snapshot of the users in the audience.

Create an Audience List

The Google Analytics Data API v1 uses an asynchronous approach to create Audience Lists. First, a request to the audienceLists.create method is necessary to create an audience list of users. Then, the audienceLists.query method is used to retrieve the users in the audience.

In addition, you can use audienceLists.get to retrieve configuration metadata about a specific Audience List and audienceLists.list to list all Audience Lists for a property.

Select a Reporting Entity

All methods of the Data API v1 require the Google Analytics 4 property identifier to be specified inside a URL request path in the form of properties/GA4_PROPERTY_ID, such as:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA4_PROPERTY_ID/audienceLists

The report is generated based on the Google Analytics event data collected in the specified Google Analytics 4 property.

If you are using one of the Data API client libraries, there is no need to manipulate the request URL path manually. Most API clients provide a property parameter that expects a string in the form of properties/GA4_PROPERTY_ID. See Quick start guide for examples of using the client libraries.

Request the Audience List Creation

To create an Audience List, call the audienceLists.create method using the AudienceList object in a request. The following parameters are required:

A valid audience name in the audience field, formatted as properties/{propertyId}/audiences/{audienceId}. You can use the audiences.list method of the Google Analytics Admin API v1 to obtain this value. The Audience.name field of the audiences.list response contains the audience name.
A valid list of dimensions in the dimensions field. The list of dimensions supported by this method can be found in the Audience List Schema documentation. Only the data for dimensions mentioned in this field is included in an Audience List.

Example Audience List creation request:

HTTP Request

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/audienceLists
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

A response of the audienceLists.create method contains the Audience List name in the name field (such as properties/1234567/audienceLists/123), which can be used in subsequent queries to retrieve the users from the Audience List.

HTTP Response

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceList",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

Query the Audience List Readiness State

It may take several minutes to generate the Audience List after the audienceLists.create call. You can obtain the readiness state for an Audience List by calling the audienceLists.get method.

Use the Audience List name (such as properties/1234567/audienceLists/123) you received from a audienceLists.create response to specify the Audience List.

Example:

HTTP Request

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/audienceLists/123

The readiness status for an Audience List is returned in the state field of a response. Once the Audience List generation is complete, its state changes from CREATING to ACTIVE.

HTTP Response

{
  "name": "properties/1234567/audienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

You can obtain the state of all Audience Lists by calling the audienceLists.list method.

Retrieve Users in an Audience List

Once the Audience List created using the audienceLists.create method is generated, call the audienceLists.query method and specify the Audience List name (such as properties/1234567/audienceLists/123).

HTTP Request

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/audienceLists/123:query

If the Audience List is ready, a response containing the list of users in an audience is returned:

HTTP Response

{
  "audienceList": {
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}

Audience List Data Expectations

The following section sets data expectations for user memberships in Audience Lists.

Data Freshness

Audience List data freshness is how long it takes Google Analytics to collect events, process events, and then update user membership in audiences. If that whole process takes 24 hours, then the Audience List data freshness is 24 hours. See Data Freshness to learn more.

Let's say a user completes their first purchase, and then 7 hours later, you create an Audience List for the "Purchasers" audience. That user will almost certainly not yet be in the "Purchasers" Audience List. In 14 to 38 hours after the first purchase, that user will likely be in new Audience Lists.

Audience Lists are Snapshots

Audience Lists are lists of users in an audience at a snapshot in time. For Google Ads remarketing, Google Analytics automatically and continually exports users in audiences to Google Ads. In contrast, with Audience Lists created using the Data API v1, you need to create a new Audience List to see the latest users in that audience.

Audience Lists are created based on the latest user memberships available. However, Audience Lists can have a data freshness of say 20 hours, and that means the Audience List will be based on all events from 20 hours prior to the current moment.

The latest membership data is updated once per day, typically during daylight hours in the property's timezone. This means that an Audience List for the same audience at 9 AM & 11 AM will likely return the same data, but an Audience List at say 3 PM may be different based on including an additional day's data.

Audience Lists Expiration

Audience Lists expire after 72 hours. New users may enter and exit an audience each day. To obtain the latest users snapshot, you need to create new audience lists for each day.

Audience List User Limits

When the size of an audience or property exceeds a user limit, Audience Lists return representative samples of the audience. These limits depend on your property type (i.e., a standard or 360 property) and are enforced in each Audience List individually. Returned users are users in the requested audience, and considered users are users that may or may not be a member of the audience.

Limit Type	Standard Property Limits	Analytics 360 Property Limits
Max returned users	2 million	200 million
Max considered users	10 million	1 billion

Reporting Identity Consistency

Reporting identity decides how users are deduplicated in reports. Audience Lists do NOT change based on the reporting identity setting. Audience Lists always identify users by User-Id then device ID.

This means that reports on an audience can show more users than the Audience List returns. For example if the Reporting Identity is "Device based" and user ID is collected, then reports will not deduplicate users based on user Id but Audience Lists will deduplicate based on user ID.

It is also possible for reports on an audience to show fewer users than the Audience List returns. For example if the Reporting Identity is "Blended", then reports will deduplicate users based on Google Signals but Audience Lists will not.

Backfill Consistency

When you create an Audience in Google Analytics and enable Google Ads remarketing, Google Analytics backfills that audience in Google Ads with recently added members. However, Google Analytics reports and Audience Lists do NOT contain backfilled audience memberships. A user will need to log an event after the audience is created for reports and Audience Lists to show the user in that audience.

For example if a user logs a purchase event on June 20th and you create a "Purchasers" audience on June 21st, then you likely need to wait until June 22nd to potentially see that user in new Audience Lists. However, that user will only be in the Audience List if the user has logged any event on June 21st.