- [HTTP request](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#body.HTTP_TEMPLATE)
- [Path parameters](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#body.PATH_PARAMETERS)
- [Request body](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#body.request_body)
  - [JSON representation](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#body.response_body)
  - [JSON representation](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#body.QueryAudienceListResponse.SCHEMA_REPRESENTATION)
- [Authorization scopes](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#body.aspect)
- [AudienceRow](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#AudienceRow)
  - [JSON representation](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#AudienceRow.SCHEMA_REPRESENTATION)
- [AudienceDimensionValue](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#AudienceDimensionValue)
  - [JSON representation](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#AudienceDimensionValue.SCHEMA_REPRESENTATION)
- [Try it!](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#try-it)

Retrieves an audience list of users. After creating an audience, the users are not immediately available for listing. First, a request to `audienceLists.create` is necessary to create an audience list of users, and then second, this method is used to retrieve the users in the audience list.

See [Creating an Audience List](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-list-basics) for an introduction to Audience Lists with examples.

Audiences in Google Analytics 4 allow you to segment your users in the ways that are important to your business. To learn more, see <https://support.google.com/analytics/answer/9267572>.

This method is available at beta stability at [audienceExports.query](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties.audienceExports/query). To give your feedback on this API, complete the [Google Analytics Audience Export API Feedback](https://forms.gle/EeA5u5LW6PEggtCEA) form.

### HTTP request

`POST https://analyticsdata.googleapis.com/v1alpha/{name=properties/*/audienceLists/*}:query`

The URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.

### Path parameters

| Parameters ||
|---|---|
| `name` | `string` Required. The name of the audience list to retrieve users from. Format: `properties/{property}/audienceLists/{audienceList}` |

### Request body

The request body contains data with the following structure:

| JSON representation |
|---|
| ``` { "offset": string, "limit": string } ``` |

| Fields ||
|---|---|
| `offset` | `string (https://developers.google.com/discovery/v1/type-format format)` Optional. The row count of the start row. The first row is counted as row 0. When paging, the first request does not specify offset; or equivalently, sets offset to 0; the first request returns the first `limit` of rows. The second request sets offset to the `limit` of the first request; the second request returns the second `limit` of rows. To learn more about this pagination parameter, see [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination). |
| `limit` | `string (https://developers.google.com/discovery/v1/type-format format)` Optional. The number of rows to return. If unspecified, 10,000 rows are returned. The API returns a maximum of 250,000 rows per request, no matter how many you ask for. `limit` must be positive. The API can also return fewer rows than the requested `limit`, if there aren't as many dimension values as the `limit`. To learn more about this pagination parameter, see [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination). |

### Response body

A list of users in an audience list.

If successful, the response body contains data with the following structure:

| JSON representation |
|---|
| ``` { "audienceRows": [ { object (`https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#AudienceRow`) } ], "audienceList": { object (`https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists#AudienceList`) }, "rowCount": integer } ``` |

| Fields ||
|---|---|
| `audienceRows[]` | ``object (`https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#AudienceRow`)`` Rows for each user in an audience list. The number of rows in this response will be less than or equal to request's page size. |
| `audienceList` | ``object (`https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists#AudienceList`)`` Configuration data about AudienceList being queried. Returned to help interpret the audience rows in this response. For example, the dimensions in this AudienceList correspond to the columns in the AudienceRows. |
| `rowCount` | `integer` The total number of rows in the AudienceList result. `rowCount` is independent of the number of rows returned in the response, the `limit` request parameter, and the `offset` request parameter. For example if a query returns 175 rows and includes `limit` of 50 in the API request, the response will contain `rowCount` of 175 but only 50 rows. To learn more about this pagination parameter, see [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination). |

### Authorization scopes

Requires one of the following OAuth scopes:

- `https://www.googleapis.com/auth/analytics.readonly`
- `https://www.googleapis.com/auth/analytics`

## AudienceRow

Dimension value attributes for the audience user row.

| JSON representation |
|---|
| ``` { "dimensionValues": [ { object (`https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#AudienceDimensionValue`) } ] } ``` |

| Fields ||
|---|---|
| `dimensionValues[]` | ``object (`https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties.audienceLists/query#AudienceDimensionValue`)`` Each dimension value attribute for an audience user. One dimension value will be added for each dimension column requested. |

## AudienceDimensionValue

The value of a dimension.

| JSON representation |
|---|
| ``` { // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "value": string // End of mutually exclusive fields. } ``` |

| Fields ||
|---|---|
| One kind of dimension value. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: ||
| `value` | `string` Value as a string if the dimension type is a string. |
| End of mutually exclusive fields. ||