Recurring audience lists

This document describes recurring audience lists, which are an advanced feature of the Google Analytics Data API v1. For an introduction to the audience list export feature, see the audience export fundamentals guide.

Recurring audience lists produce audience lists daily as audience memberships change, to ensure you're working with the most recent data.

Regular (non-recurring) audience lists are static lists of users in the audience at the time the list is generated.

Create a new audience list daily

It takes a variable amount of time to process one day's audience data and update membership. There's no way to be sure that the audience list data is updated in 24 hours.

For example, even if you request an audience list at the same time each day, on some days the audience list will be the same as the previous day, and on other days, the audience list will be different and contain an additional day of membership changes.

Audience lists are based on event data from one day before the most recent membership changes. If you create an audience list before daily membership updates occur, it will use data from the two days before. If you create an audience list after daily membership updates occur, it will use data from yesterday.

Periodically poll a recurring audience list

Recurring Audience Lists only produce Audience Lists when an additional day's data is available. This removes the guesswork of deciding when to create new Audience Lists. Instead, you can cheaply poll the Recurring Audience List throughout the day to see if additional data is available.

Create a Recurring Audience List

To create a recurring audience list, call the recurringAudienceLists.create method using the RecurringAudienceList 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 List.

Here's a sample recurring audience list creation request:

HTTP Request

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

A response of the recurringAudienceLists.create method contains the name in the name field (such as properties/1234567/recurringAudienceLists/123), which can be used in subsequent queries to retrieve the configuration metadata for this recurring audience list. Also, the configuration metadata contains resource names for audience list instances created for this recurring audience list.

HTTP Response

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

Poll configuration metadata

Use the recurringAudienceLists.get method to retrieve configuration metadata about a specific recurring audience list. The configuration metadata contains resource names for audience list instances created for this recurring audience list.

Here's an example:

HTTP Request

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

An instance of RecurringAudienceList is returned in response. It contains the configuration metadata, which includes resource names for audience list instances created for this recurring audience list.

HTTP Response

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

You can use recurringAudienceLists.list to list all recurring audience lists for a property.

Use Webhooks to receive asynchronous notifications about new audience lists

Instead of periodically polling the configuration metadata about a specific recurring audience list using the recurringAudienceLists.get method, you can asynchronously receive Webhook notifications when an audience list becomes available.

To configure Webhook notifications, specify the webhookNotification field when creating a new recurring audience list.

Follow the Async audience lists with webhooks guide for more information about using Webhooks in the Google Analytics Data API v1.

Retrieve users in an audience export

To retrieve users in an Audience Export, call the audienceExports.query method and specify the Audience Export name retrieved from the configuration metadata provided by recurringAudienceLists.get or recurringAudienceLists.list.

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
}