---
title: "Get audience sizing"
method: POST
path: "/ad_accounts/{ad_account_id}/ad_groups/audience_sizing"
tags: ["ad_groups"]
---

# Get audience sizing

`POST /ad_accounts/{ad_account_id}/ad_groups/audience_sizing`

## Request

- Base URL: `https://api.pinterest.com/v5`
- URL: `https://api.pinterest.com/v5/ad_accounts/{ad_account_id}/ad_groups/audience_sizing`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://www.pinterest.com/oauth/`
    - Token URL: `https://api.pinterest.com/v5/oauth/token` scopes: `ads:read`
  - OAuth 2
    - Client credentials
    - Token URL: `https://api.pinterest.com/v3/oauth/access_token/` scopes: `ads:read`
- TypeScript: <https://skmtc.dev/pinterest/apis/pinterest-rest-api/docs/ad_accounts/:ad_account_id/ad_groups/audience_sizing/post.ts> (a function with typed inputs; its response is checked against the schema)

Get potential audience size for an ad group with given targeting criteria.
Potential audience size estimates the number of people you may be able to reach per month with your campaign.
It is based on historical advertising data and the targeting criteria you select.
It does not guarantee results or take into account factors such as bid, budget, schedule, seasonality or product experiments.

## Path parameters

- `ad_account_id` string, required

## Request body

- AdGroupAudienceSizingCreate: Resource create operation model.
  - `auto_targeting_enabled` boolean: Enable auto-targeting for ad group. Default value is True. Also known as [Pinterest Performance+ targeting](https://help.pinterest.com/en/business/article/performance-plus-targeting).
  - `creative_types` AdGroupAudienceSizingCreativeTypes[], nullable: Pin creative types filter. **Note:** SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.
  - `keywords` AdGroupAudienceSizingKeyword[], nullable: Array of keyword objects. If the keywords field is missing, all keywords will be targeted.
    - `match_type` 'BROAD' | 'PHRASE' | 'EXACT' | 'EXACT_NEGATIVE' | 'PHRASE_NEGATIVE', required: Keyword match type
    - `value` string, required: Keyword value (120 chars max).
  - `placement_group` 'ALL' | 'SEARCH' | 'BROWSE' | 'OTHER': Campaign placement group type
  - `product_group_ids` AdGroupAudienceSizingProductGroupId[], nullable: Targeted product group IDs. **Note:** This can only be combined with shopping/catalog sales campaigns. For more information, [click here](https://help.pinterest.com/en/business/article/shopping-ads#section-14571). SHOPPING_RETARGETING must be included in targeting_spec object or this field will be ignored.
  - `targeting_spec` TargetingSpecOptimal
    - `AGE_BUCKET` TargetingSpecAgeBucket[], nullable: **Legacy field.** Predefined age ranges. We recommend using MINIMUM_AGE and MAXIMUM_AGE instead for more flexible targeting. Cannot be combined with MINIMUM_AGE/MAXIMUM_AGE. If neither AGE_BUCKET nor MINIMUM_AGE/MAXIMUM_AGE are specified, all ages will be targeted.
    - `APPTYPE` TargetingSpecAppType[], nullable: Allowed devices. If the APPTYPE field is missing, the default behavior in terms of ad delivery is that **All devices/apptypes** will be targeted.
    - `AUDIENCE_EXCLUDE` PinterestLibIntegerFormatType[], nullable: Excluded customer list IDs. Used to drive new customer acquisition goals. For example: ["2542620905475"]. Audience lists need to have at least 100 people with Pinterest accounts in them. If the AUDIENCE_EXCLUDE field is missing, the default behavior in terms of ad delivery is that **No users will be excluded**.
    - `AUDIENCE_INCLUDE` PinterestLibIntegerFormatType[], nullable: Targeted customer list IDs. For example: ["2542620905473"]. Audience lists need to have at least 100 people with Pinterest accounts in them Audience lists need to have at least 100 people with Pinterest accounts in them. If the AUDIENCE_INCLUDE field is missing, the default behavior in terms of ad delivery is that **All users will be included**.
    - `GENDER` TargetingSpecGender[], nullable: Targeted genders. Values: ["unknown","male","female"]. If the GENDER field is missing, the default behavior in terms of ad delivery is that **All genders will be targeted**.
    - `GEO` string[], nullable: Region codes or postal codes to include for targeting. Region codes represent broader geographical areas. Example: `US-CA` is the region code for California in the United States. Postal codes represent more granular, specific areas. Example: `94103` is a postal code for a specifc area in San Francisco, California, U.S.A. For each ad group, use only one of these methods, depending on which fits your targeting needs. Do not use both. For example, either specify a broader region code like `US-CA` or a more granular postal code within that regon, such as `94103`. You can specify multiple region codes or postal codes in an array, depending on which method you choose. Precede a region code array with the `region_codes` key and a postal code value with the `postal_codes` key. Examples: ``` "geo": { "region_codes": ["US-CA"] } ``` ``` "geo": { "postal_codes": ["94103"] } ``` For each ad group, specify at least one `GEO` or `LOCATION`. If you do not specifiy a `GEO` code, only `LOCATION` values will be targeted (See `LOCATION` parameter in this targeting spec.). Learn how to [get a current, complete list of codes](/docs/analytics-and-reports/ads-reporting/#get-all-available-codes-and-zones).
    - `GEO_EXCLUDE` string[]: [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Region codes or postal codes to exclude from the targeting inclusion area. See `GEO` parameter in this targeting spec for rules, syntax, and other information.
    - `INTEREST` string[]: Array of interest object IDs. If the INTEREST field is missing, the default behavior in terms of ad delivery is that **All interests will be targeted**.
    - `LOCALE` string[], nullable: 24 ISO 639-1 two-letter language codes. If the LOCALE field is not included in the request, all languages are targeted.
    - `LOCATION` string[], nullable: Metropolitan codes and/or ISO-Alpha-2, two-letter country codes to include for targeting. Precede country code values with the `country_codes` key and metro code values with `metro_codes` key. Example: ``` "location": { "country_codes": ["US", "CA"], "metro_codes": ["501", "602"] } ``` For each ad group, specify at least one `GEO` or `LOCATION` code. If you do not specify a `LOCATION` code, only `GEO` values will be targeted (See `GEO` parameter in this targeting spec.). Learn how to [get a current, complete list of codes](/docs/analytics-and-reports/ads-reporting/#get-all-available-codes-and-zones).
    - `LOCATION_EXCLUDE` string[]: [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Metropolitan codes and/or ISO-Alpha-2, two-letter country codes to exclude from targeting. See `LOCATION` parameter in this targeting spec for rules, syntax, and other information.
    - `MAXIMUM_AGE` string: Maximum age to target (inclusive). Values: "18", "19", ..., "65", "65+". Must be used together with `MINIMUM_AGE`. Cannot be combined with `AGE_BUCKET`. If neither `MINIMUM_AGE`/`MAXIMUM_AGE` nor `AGE_BUCKET` are specified, all ages will be targeted.
    - `MINIMUM_AGE` string: Minimum age to target (inclusive). Values: "18", "19", ..., "65". Note: 65+ is not allowed for minimum age. Must be used together with `MAXIMUM_AGE`. Cannot be combined with `AGE_BUCKET`. If neither `MINIMUM_AGE`/`MAXIMUM_AGE` nor `AGE_BUCKET` are specified, all ages will be targeted.
    - `SHOPPING_RETARGETING` TargetingSpecShoppingRetargeting[], nullable: Array of object: lookback_window [Integer]: Number of days ago to start lookback timeframe for dynamic retargeting tag_types [Array of integer]: Event types to target for dynamic retargeting exclusion_window [Integer]: Number of days ago to stop lookback timeframe for dynamic retargeting
      - `exclusion_window` integer: Number of days ago to stop lookback timeframe for dynamic retargeting
      - `lookback_window` integer: Number of days ago to start lookback timeframe for dynamic retargeting
      - `tag_types` integer[]: Event types to target for dynamic retargeting
    - `TARGETING_STRATEGY` TargetingStrategy[], nullable

## Response `200`

The request has succeeded.

- AdGroupAudienceSizing
  - `audience_size_lower_bound` number: The lower confidence bound of the estimated potential audience size. "Potential audience size" estimates the number of people you may be able to reach per month with your campaign. It is based on historical advertising data and the targeting criteria you select. It does not guarantee results or take into account factors such as bid, budget, schedule, seasonality or product experiments.
  - `audience_size_upper_bound` number: The upper confidence bound of the estimated potential audience size. "Potential audience size" estimates the number of people you may be able to reach per month with your campaign. It is based on historical advertising data and the targeting criteria you select. It does not guarantee results or take into account factors such as bid, budget, schedule, seasonality or product experiments.

## Other responses

- `201`: Resource create operation completed successfully.
- `400`: The request could not be understood by the server due to unexpected data.
- `401`: Authentication is required and has either failed or not been provided.
- `403`: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
- `404`: The requested resource could not be found on this server.
- `429`: The user has sent too many requests in a given amount of time and is being rate limited.
- `default`: An unexpected error response.

## Changes

- **2026-06-04** (v5) `b698c180678a`: 5 breaking, 1 warning, 8 info
  - added `#/components/schemas/AdgroupPlacementGroupType` to the `placement_group` request property `allOf` list
  - the request property `keywords/items/match_type` became not nullable
  - removed the enum value `undefined` of the request property `keywords/items/match_type`
  - the `placement_group` request property type changed from `string` to no type
  - …10 more
- **2025-12-11** (v5) `79f62f71f05b`: 1 breaking
  - request body became required
- **2025-12-10** (v5) `6768e3ca1ffa`: 2 info
  - added the new optional request property `targeting_spec/MAXIMUM_AGE`
  - added the new optional request property `targeting_spec/MINIMUM_AGE`
- **2025-04-04** (v5) `10f9eba4ad97`: 3 info
  - the endpoint scheme security `client_credentials` was added to the API
  - added the new `19+` enum value to the request property `targeting_spec/AGE_BUCKET/items/`
  - added the new `20+` enum value to the request property `targeting_spec/AGE_BUCKET/items/`
- **2024-04-23** (v5) `f9321315766f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pinterest/apis/pinterest-rest-api/changes/ad_accounts/:ad_account_id/ad_groups/audience_sizing/post.md)

---

[API](https://skmtc.dev/pinterest/apis/pinterest-rest-api.md) - [All operations](https://skmtc.dev/pinterest/apis/pinterest-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pinterest/apis/pinterest-rest-api/revisions/b698c180678a?raw)