Query Location Groups
Retrieve a paginated list of location groups using filters and sorting.
URL
POST https://api.ads.apple.com/v1/location-groups/queryHeader Parameters
| Name | Type | Description |
|---|---|---|
X-Ap-Context Required | string |
Response Codes
| Status | Reason | Type | Description |
|---|---|---|---|
| 200 | OK Content-Type: application/json | LocationGroupQueryResponse | |
| 400 | Bad Request Content-Type: application/json | LocationGroupQueryResponse | |
| 401 | Unauthorized Content-Type: application/json | Error | |
| 403 | Forbidden Content-Type: application/json | Error | |
| 404 | Not Found Content-Type: application/json | Error | |
| 429 | Too Many Requests Content-Type: application/json | Error | |
| 500 | Internal Server Error Content-Type: application/json | Error |
Discussion
This endpoint returns a paginated list of location groups accessible to the authenticated ad account. An empty request body returns all non-deleted groups with default pagination applied.
See QueryFilterOperator for the full set of supported comparison operators.
Request Body
See QueryRequest.
Field | Type | Required | Description |
|---|---|---|---|
| array | No | Filter conditions to narrow results. |
| array | No | Sort order for results (field + ASC/DESC). |
| object | No | Offset and page size. Defaults apply if omitted. |
Filterable Fields
The system combines multiple filters with AND logic. The id filter matches the group’s system-assigned identifier, the same id value returned in create and get responses, not the provider object ID. Filtering by brandId is the most common way to scope results to a single brand’s groups.
The system excludes soft-deleted groups from results by default. To include them, add a filter with field: "deleted", operator: "EQUALS", value: true.
Field | Type | Operators | Sortable | Description |
|---|---|---|---|---|
| string |
| Yes | Matches the group’s system-assigned identifier. |
| string |
| Yes | Group display name. |
| string |
| Yes | Parent brand. |
| string (enum) |
| Yes |
|
| boolean |
| Yes | Soft-delete flag. Defaults to excluding deleted groups. |
| boolean |
| Yes | All-locations group flag. |
| string (enum) |
| Yes | Eligibility status. |
| string |
| Yes | Blocked placement. |
| string |
| Yes | Blocked country. |
| string |
| Yes | Allowed placement. |
| string |
| Yes | Allowed country. |
Sorting and Pagination
You can sort results by any filterable field using the sorting array; see QuerySort (QuerySortOrder) and QueryPagination for the request shape. The response includes a pagination object with totalCount, offset, and pageSize. Page through large result sets by incrementing offset.