---
title: "Returns a list of ad groups for an advertiser"
method: GET
path: "/api/v3/advertisers/{advertiserId}/adgroups"
tags: ["AdGroup"]
---

# Returns a list of ad groups for an advertiser

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

## Request

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

## Path parameters

- `advertiserId` string, required

## Query parameters

- `campaignId` string
- `includeArchived` boolean
- `cursor` string
- `pageSize` integer, required

## Response `200`

The list of ad groups for the advertisers with the id specified in the URL, 
filtered by campaign id if provided

- object
  - `adgroups` object[]: The list of ad groups returned in this paginated call
    - `cursor` string: The cursor of the ad group
    - `data` object: The ad group data
      - `advertiser_id` string: The advertiser id that this ad group is tied to
      - `bid` object: The user configured bid for this ad group
        - `amount` string, nullable: The user set bid amount for the ad group if set
        - `bid_strategy` 'AUTO_BID' | 'MAX_BID': The user configured bid strategy for this ad group
        - `pricing_type` 'CPM' | 'CPC' | 'CPM_MAX_IMPRESSIONS': The pricing type chosen by the user
      - `budget` object: The user configured budget for this ad group
        - `amount` string: The user set budget amount for the ad group
        - `budget_type` 'DAILY_CAP_MONEY' | 'LIFETIME_CAP_MONEY': The budget type chosen by the user
      - `campaign_id` string: The campaign id that this ad group is tied to
      - `created_at` string, date-time: The creation time of the ad group
      - `end_time` string, date-time, nullable: The end time for this ad group
      - `frequency_caps` object[]: The frequency cap data for this adgroup
        - `max_impressions` integer
        - `num_timeunits` integer
        - `timeunit` 'MINUTE' | 'HOUR' | 'DAY' | 'WEEK' | 'MONTH'
      - `id` string: The id of the ad group
      - `name` string: The name of the ad group
      - `placements` string[]: The placements configured for this ad group
      - `start_time` string, date-time: The start time for this ad group
      - `status` 'DRAFT' | 'ACTIVE' | 'PARTIALLY_ACTIVE' | 'NO_ADS' | 'ARCHIVED' | 'PAUSED' | 'PAUSED_DUE_TO_CAMPAIGN_PAUSE' | 'COMPLETED' | 'PENDING' | 'INELIGIBLE': The delivery status of the ad group
      - `targeting` object: The targeting configured for this adgroup
        - `audience_targeting_ids` string[]: The audience targeting feature ids set for an ad group
        - `custom_audience_targeting` object, nullable: The custom audience boolean targeting data for an ad group
          - `exclude` array[]: A list of lists of IDs to exclude in targeting. IDs within each inner list are unioned (OR), and the inner lists are intersected (AND)
            - unknown[]
              - …
          - `include` array[]: A list of lists of IDs to include in targeting. IDs within each inner list are unioned (OR), and the inner lists are intersected (AND).
            - unknown[]
              - …
        - `excluded_location_targeting_ids` string[]: The excluded location targeting feature ids set for an ad group
        - `geo_source_types` string[]: The geo source types to target on for the ad group
        - `included_location_targeting_ids` string[]: The included location targeting feature ids set for an ad group
        - `interests_targeting` object, nullable: The interests boolean targeting data for an ad group
          - `exclude` array[]: A list of lists of IDs to exclude in targeting. IDs within each inner list are unioned (OR), and the inner lists are intersected (AND)
            - unknown[]
              - …
          - `include` array[]: A list of lists of IDs to include in targeting. IDs within each inner list are unioned (OR), and the inner lists are intersected (AND).
            - unknown[]
              - …
        - `time_of_day` object: The time of day targeting data for an ad group
          - `excluded` object[]: The time of day data set to be excluded for targeting
            - `days` string[]
            - `time` object
              - …
          - `included` object[]: The time of day data set to be included for targeting
            - `days` string[]
            - `time` object
              - …
      - `updated_at` string, date-time: The last updated time of the ad group
      - `user_status` 'DRAFT' | 'ACTIVE' | 'PAUSED' | 'ARCHIVED': The user set status of the ad group
  - `page_info` object: The pagination info for the api caller to get the rest of the advertiser's ad groups
    - `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)