Audience Export 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 or application based on shared attributes.

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

Create an Audience Export

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

In addition, you can use audienceExports.get to retrieve configuration metadata about a specific Audience Export and audienceExports.list to list all Audience Exports 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/v1beta/properties/GA4_PROPERTY_ID/audienceExports

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 Export creation

To create an Audience Export, call the audienceExports.create method using the AudienceExport 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 Export Schema documentation. Only the data for dimensions mentioned in this field is included in an Audience Export.

Example Audience Export creation request:

HTTP Request

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

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

HTTP Response

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

Query the Audience Export readiness state

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

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

Example:

HTTP Request

GET https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123

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

HTTP Response

{
  "name": "properties/1234567/audienceExports/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 Exports by calling the audienceExports.list method.

Retrieve users in an Audience Export

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

HTTP Request

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

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

HTTP Response

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/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 Export data expectations

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

Data freshness

Audience Export 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 Export data freshness is 24 hours. See Data Freshness to learn more.

For example, if a user completes their first purchase, and then 7 hours later, you create an Audience Export for the "Purchasers" audience, the user will almost certainly not yet be in the "Purchasers" Audience Export. In 14 to 38 hours after the first purchase, that user will likely be in new Audience Exports.

Audience Exports are snapshots

Audience Exports 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 Exports created using the Data API v1, you need to create a new Audience Export to see the latest users in that audience.

Audience Exports are created based on the latest user memberships available. However, Audience Exports can have a data freshness of say 20 hours, and that means the Audience Export 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 Export for the same audience at 9 AM & 11 AM will likely return the same data, but an Audience Export at say 3 PM may be different based on including an additional day's data.

Audience Exports expiration

Audience Exports 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 Exports for each day.

Audience Export user limits

When the size of an audience or property exceeds a user limit, Audience Exports 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 Export 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 Exports do NOT change based on the reporting identity setting. Audience Exports always identify users by User-Id then device ID.

This means that reports on an audience can show more users than the Audience Export returns. For example if the Reporting Identity is "Device based" and user ID is collected, then reports won't deduplicate users based on user ID but Audience Exports will deduplicate based on user ID.

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 Exports do NOT contain backfilled audience memberships. A user will need to log an event after the audience is created for reports and Audience Exports 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 Exports. However, that user will only be in the Audience Export if the user has logged any event on June 21st.