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](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-export-basics). 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. ![Creating a new Audience List daily](https://developers.google.com/static/analytics/devguides/reporting/data/v1/images/audience-list-daily.png) 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. ![Periodically polling a recurring Audience List during the day](https://developers.google.com/static/analytics/devguides/reporting/data/v1/images/audience-list-recurring.png) ## Create a recurring audience list To create a recurring audience list, call the [`recurringAudienceLists.create`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.recurringAudienceLists/create) method using the [`RecurringAudienceList`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.recurringAudienceLists#RecurringAudienceList) object in a request. The following parameters are required: - A valid audience name in the [`audience`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.recurringAudienceLists#RecurringAudienceList.FIELDS.audience) field, formatted as `properties/{propertyId}/audiences/{audienceId}`. You can use the [`audiences.list`](https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties.audiences/list) method of the Google Analytics Admin API v1 to obtain this value. The [`Audience.name`](https://developers.google.com/analytics/devguides/config/admin/v1/rest/v1alpha/properties.audiences#Audience.FIELDS.name) field of the `audiences.list` response contains the audience name. - A valid list of dimensions in the [`dimensions`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.recurringAudienceLists#RecurringAudienceList.FIELDS.dimensions) field. The list of dimensions supported by this method can be found in the [Audience Export Schema](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-export-api-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](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.recurringAudienceLists#RecurringAudienceList.FIELDS.audience_lists) 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`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.recurringAudienceLists/get) method to retrieve configuration metadata about a specific recurring audience list. The configuration metadata contains [resource names for audience list instances](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.recurringAudienceLists#RecurringAudienceList.FIELDS.audience_lists) 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`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.recurringAudienceLists#RecurringAudienceList) is returned in response. It contains the configuration metadata, which includes [resource names for audience list instances](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.recurringAudienceLists#RecurringAudienceList.FIELDS.audience_lists) 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`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.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`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.recurringAudienceLists/get) method, you can asynchronously receive Webhook notifications when an audience list becomes available. To configure Webhook notifications, specify the [`webhookNotification`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.recurringAudienceLists#RecurringAudienceList) field when creating a new recurring audience list. Follow the [`Async audience lists with webhooks`](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-lists-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`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports/query) method and specify the Audience Export name retrieved from the configuration metadata provided by [`recurringAudienceLists.get`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.recurringAudienceLists/get) or [`recurringAudienceLists.list`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.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 }