REST Resource: properties.audienceLists

Resource: AudienceList

An audience list is a list of users in an audience at the time of the list's creation. One audience may have multiple audience lists created for different days.

JSON representation
  "name": string,
  "audience": string,
  "audienceDisplayName": string,
  "dimensions": [
      object (AudienceDimension)
  "creationQuotaTokensCharged": integer,
  "state": enum (State),
  "beginCreatingTime": string,
  "rowCount": integer,
  "errorMessage": string,
  "percentageCompleted": number,
  "recurringAudienceList": string,
  "webhookNotification": {
    object (WebhookNotification)


Output only. Identifier. The audience list resource name assigned during creation. This resource name identifies this AudienceList.

Format: properties/{property}/audienceLists/{audienceList}



Required. The audience resource name. This resource name identifies the audience being listed and is shared between the Analytics Data & Admin APIs.

Format: properties/{property}/audiences/{audience}



Output only. The descriptive display name for this audience. For example, "Purchasers".


object (AudienceDimension)

Required. The dimensions requested and displayed in the query response.



Output only. The total quota tokens charged during creation of the AudienceList. Because this token count is based on activity from the CREATING state, this tokens charged will be fixed once an AudienceList enters the ACTIVE or FAILED states.


enum (State)

Output only. The current state for this AudienceList.


string (Timestamp format)

Output only. The time when audienceLists.create was called and the AudienceList began the CREATING state.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".



Output only. The total number of rows in the AudienceList result.



Output only. Error message is populated when an audience list fails during creation. A common reason for such a failure is quota exhaustion.



Output only. The percentage completed for this audience export ranging between 0 to 100.



Output only. The recurring audience list that created this audience list. Recurring audience lists create audience lists daily.

If audience lists are created directly, they will have no associated recurring audience list, and this field will be blank.


object (WebhookNotification)

Optional. Configures webhook notifications to be sent from the Google Analytics Data API to your webhook server. Use of webhooks is optional. If unused, you'll need to poll this API to determine when an audience list is ready to be used. Webhooks allow a notification to be sent to your servers & avoid the need for polling.

Either one or two POST requests will be sent to the webhook. The first POST request will be sent immediately showing the newly created audience list in its CREATING state. The second POST request will be sent after the audience list completes creation (either the ACTIVE or FAILED state).

If identical audience lists are requested in quick succession, the second & subsequent audience lists can be served from cache. In that case, the audience list create method can return an audience list is already ACTIVE. In this scenario, only one POST request will be sent to the webhook.


The AudienceList currently exists in this state.

STATE_UNSPECIFIED Unspecified state will never be used.
CREATING The AudienceList is currently creating and will be available in the future. Creating occurs immediately after the audienceLists.create call.
ACTIVE The AudienceList is fully created and ready for querying. An AudienceList is updated to active asynchronously from a request; this occurs some time (for example 15 minutes) after the initial create call.
FAILED The AudienceList failed to be created. It is possible that re-requesting this audience list will succeed.



Creates an audience list for later retrieval.


Exports an audience list of users to a Google Sheet.


Gets configuration metadata about a specific audience list.


Lists all audience lists for a property.


Retrieves an audience list of users.