---
title: "Returns a list of audiences for the advertiser."
method: GET
path: "/api/v3/advertisers/{advertiserId}/audiences"
tags: ["Audiences"]
---

# Returns a list of audiences for the advertiser.

`GET /api/v3/advertisers/{advertiserId}/audiences`

## Request

- Base URL: `https://ads.nextdoor.com`
- URL: `https://ads.nextdoor.com/api/v3/advertisers/{advertiserId}/audiences`
- Auth: HTTP bearer

## Path parameters

- `advertiserId` string, required

## Query parameters

- `cursor` string
- `pageSize` integer, required

## Response `200`

A list of custom audiences for the advertiser paginated

- object
  - `audiences` object[]: The list of audiences returned in this paginated call.
    - `cursor` string: The cursor of the audience.
    - `data` union: The audience data.
      - object
        - `advertiser_id` string: The advertiser which owns the audience.
        - `audience_size` integer, nullable: The size of the audience.
        - `audience_type` 'ADDRESSES' | 'EMAILS' | 'EMAIL_AND_ADDRESSES' | 'POSTAL_CODES', nullable: The audience type.
        - `created_at` string, date-time: The creation timestamp
        - `description` string, nullable: The description of the audience.
        - `id` string: The id of the audience.
        - `name` string: The name of the audience.
        - `status` 'ACTIVE' | 'PENDING' | 'ARCHIVED' | 'FAILED' | 'PAUSED': The status of the custom audience.
        - `updated_at` string, date-time: The timestamp of the last update for this audience.
      - object
        - `advertiser_id` string: The advertiser which owns the audience.
        - `audience_size` integer, nullable: The size of the audience.
        - `audience_type` 'RETARGETING_PIXEL' | 'RETARGETING_ENGAGEMENT' | 'RETARGETING_CAPI', nullable: The audience type.
        - `created_at` string, date-time: The creation timestamp
        - `description` string, nullable: The description of the audience.
        - `id` string: The id of the audience.
        - `name` string: The name of the audience.
        - `retargeting_data` union: The retargeting data.
          - object
            - `capi_retargeting_data` object: Data required to create a capi retargeting audience.
              - …
            - `lookback_window_ms` integer: The lookback window for the audience in ms
          - object
            - `engagement_retargeting_data` object: Data required to create an engagement retargeting audience.
              - …
            - `lookback_window_ms` integer: The lookback window for the audience in ms
          - object
            - `lookback_window_ms` integer: The lookback window for the audience in ms
            - `pixel_retargeting_data` object: Data required to create a pixel retargeting audience.
              - …
        - `status` 'ACTIVE' | 'PENDING' | 'ARCHIVED' | 'FAILED' | 'PAUSED': The status of the custom audience.
        - `updated_at` string, date-time: The timestamp of the last update for this audience.
  - `page_info` object: The pagination info for the api caller to get the rest of the advertiser's audiences.
    - `end_cursor` string, nullable: The end cursor of the current page result, typically this is the cursor of the last object.
    - `page_size` integer: The number of results returned in this page.

## Other responses

- `400`: Bad Request. Indicates that the server cannot process the request due to client-side error. For example invalid input.
- `401`: Unauthorized. The API key is invalid and needs to be re-generated.
- `403`: Forbidden. The token passed in has been successfully authenticated, but can’t perform the given action due to not having sufficient permissions.
- `500`: Internal server error.
- `503`: The server is temporarily unable to handle the request due to maintenance or overload.

---

[API](https://skmtc.dev/nextdoor/apis/advertising.md) - [All operations](https://skmtc.dev/nextdoor/apis/advertising/llms.txt) - [OpenAPI document](https://skmtc.dev/nextdoor/apis/advertising/revisions/cdbbecabcffc?raw)