--- title: "List audiences" method: GET path: "/ad_accounts/{ad_account_id}/audiences" tags: ["audiences"] --- # List audiences `GET /ad_accounts/{ad_account_id}/audiences` Get list of audiences for the ad account. ## Path parameters - `ad_account_id` string, required ## Query parameters - `bookmark` string - `page_size` integer - `order` 'ASCENDING' | 'DESCENDING' - `ownership_type` 'OWNED' | 'RECEIVED' — Filter audiences by ownership type. - `exclude_nca` boolean ## Response `200` The request has succeeded. - object - `bookmark` string, nullable - `items` AdAccountsAudience[], required - `ad_account_id` string — Ad account ID. - `audience_type` 'CUSTOMER_LIST' | 'VISITOR' | 'ENGAGEMENT' | 'ACTALIKE' | 'PERSONA' — Audience type - `created_by_company_name` string, nullable — The company that created this audience. - `created_timestamp` integer, nullable — Creation time. Unix timestamp in seconds. - `description` string, nullable — Audience description. - `id` string, required — Audience ID. - `is_nca` boolean — Whether the audience derives from a new customer acquisition (expanded matching) customer list. Read-only. - `name` string — Audience name. - `rule` AdAccountsAudienceRule — JSON object defining targeted audience users. Example rule formats per audience type: CUSTOMER_LIST: { "customer_list_id": ""} ACTALIKE: { "seed_id": [""], "country": "US", "percentage": "10" } (Valid countries include: "US", "CA", and "GB". Percentage should be 1-10. The targeted audience should be this % size across Pinterest.) VISITOR: { "visitor_source_id": [""], "retention_days": "180", "event_source": {"=": ["web", "mobile"]}, "ingestion_source": {"=": ["tag"]}} (Retention days should be 1-540. Retention applies to specific customers.) ENGAGEMENT: {"engagement_domain": ["www.example.com"], "engager_type": 1} Learn more about [engagement audiences](/docs/work-with-targets-and-audiences/create-audiences/#engagement-audience). - `ad_account_id` string — Ad account ID. - `ad_id` string[] — Ad ID for engagement audience filter. - `campaign_id` string[] — Campaign ID for engagement audience filter. - `country` string — Valid countries include: "US", "CA", and "GB". - `customer_list_id` string — Customer list ID. For CUSTOMER_LIST `audience_type`. - `engagement_domain` string[] — The audience account's verified domain. **Required** for ENGAGEMENT `audience_type`. - `engagement_type` string — Engagement type enum. Optional for ENGAGEMENT `audience_type`. Supported values are `click`, `save`, `closeup`, `comment` and `like`. All engagements are included if this field is not set. - `engager_type` integer — Optional for ENGAGEMENT. Engager type value should be 1-2. - `event` string — A Pinterest tag event. Optional for VISITOR `audience_type`. Possible values are `pagevisit`, `signup`, `checkout`, `viewcategory`, `search`, `addtocart`, `watchvideo`, `lead`, and `custom`. This field also accepts a partner-defined Pinterest tag event. - `event_data` EventData — Optional for VISITOR `audience_type`. With the Pinterest tag, you can use event data to capture event details from your website. This object lists all the available predefined event data fields in the Pinterest tag. You can include these event data fields as part of a VISITOR audience’s `rule`; however, you **must** specify an `event` for the `event_data` fields to be evaluated. Besides what’s listed, you can also create your own set of `event_data` fields and define their usages or purposes according to your website needs. However, the benefit of using the predefined event data fields is that we can provide various metrics based on those fields' data. Examples per `event` type: `pagevisit` "event_data": { "page_name": "My online store 123 | view items | shoe" } `signup` "event_data": { "lead_type": "New release promotion" } `checkout` "event_data": { "value": 116, "order_quantity": 2, "currency": "USD", "line_items": [ { "product_name": "Pillows (Set of 2)", "product_id": "11", "product_price": 48, "product_quantity": 1 }, { "product_name": "Pillows, Large (Set of 2)", "product_id": "15", "product_price": 68, "product_quantity": 1 } ] } `addtocart` "event_data": { "value": 499, "order_quantity": 1, "currency": "USD", "line_items": [ { "product_name": "Red leather boots", "product_id": "3486", "product_category": "shoe", "product_variant_id": "JB11103000", "product_price": 499, "product_quantity": "1", "product_brand": "My brand" }]} `watchvideo` "event_data": { "video_title" : "My Product Video 01" } `lead` "event_data": { "lead_type": "Newsletter" } - `currency` 'UNK' | 'USD' | 'GBP' | 'CAD' | 'EUR' | 'AUD' | 'NZD' | 'SEK' | 'ILS' | 'CHF' | 'HKD' | 'JPY' | 'SGD' | 'KRW' | 'NOK' | 'DKK' | 'PLN' | 'RON' | 'HUF' | 'CZK' | 'BRL' | 'MXN' | 'ARS' | 'CLP' | 'COP' | 'INR' | 'TRY' — Currency Codes from ISO 4217 - `lead_type` string — Promotion code. For example, 'Newsletter'. - `line_items` LineItem - `product_brand` string — Product brand. For example, 'Parker'. - `product_category` string — Product category. For example, 'Shoes'. - `product_id` integer — Product ID. For example, 1414. - `product_name` string — Product name. For example, 'Parker Boots'. - `product_price` string — Product price. For example, '99.99'. - `product_quantity` integer — Product quantity. For example, 2. - `product_variant` string — Product variant. For example, 'Red'. - `product_variant_id` string — Product variant ID. For example, '1414-34832'. - `order_id` string — Order ID. For example, 'X-151481'. - `order_quantity` integer — Order quantity. For example, 1. - `page_name` string — Page name. For example, 'Our Favorite Pins on Pinterest'. - `promo_code` string — Promotion code. For example, 'WINTER10'. - `property` string — Property. For example, 'Athleta'. - `search_query` string — Search query string. For example, 'boots'. - `value` string — Product value. For example, '199.98'. - `video_title` string — Video title. For example, 'How to style your Parker Boots'. - `event_source` object — Optional for VISITOR. You can use it as a {'=': [value]}. Supported values are: web, mobile, offline - `ingestion_source` object — Optional for VISITOR. You can use it as a {'=': [value]}. Supported values are: tag, mmp, file_upload, conversions_api - `objective_type` AudienceObjectiveType[] — Objective for engagement audience filter. - `percentage` union — Percentage should be 1-10. The targeted audience should be this % size across Pinterest. - string - integer - `pin_id` string[] — IDs of engaged organic pins. Optional for ENGAGEMENT `audience_type`. For example, "pin_id:": ["34567"] - `prefill` boolean — Optional for VISITOR `audience_type`. If `true`, the specified rule on existing engagement data is applied to pre-populate the audience. If `false`, the audience is empty at creation time. The default is `true`. - `retention_days` integer — Number of days a Pinterest user remains in the audience. Optional for ENGAGEMENT and VISITOR `audience_type`. Accepted range is 1-540. Defaults to 180 if not specified. - `seed_id` union — Audience ID(s). For ACTALIKE `audience_type`. - integer[] - string[] - `url` string[] — Optional for ENGAGEMENT or VISITOR `audience_type`. For ENGAGEMENT, it is the engaged pin's URL. For VISITOR, you can use it as a string or a {operator: value} object for filtering visitors based on conversion tag event URLs. Supported operators are [ =, !=, contains, not_contains]. Example 1: "url": "http://www.myonlinestore123.com/view_item/shoe" Example 2: "url": {"contains": "/view_item/shoe"} - `visitor_source_id` union — The conversion tag ID, or the Pinterest tag ID, that you use on your website. For VISITOR `audience_type`. - string - string[] - `size` integer, nullable — Audience size. - `status` 'INITIALIZING' | 'READY' | 'TOO_SMALL' | 'ELIGIBLE' | 'PERSONAS_INELIGIBLE_SIZE' | 'PERSONAS_INITIALIZING' — Audience processing status - `type` string — Always "audience". - `updated_timestamp` integer, nullable — Last update time. Unix timestamp in seconds. ## Other responses - `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. --- [API](https://skmtc.net/pinterest/apis/pinterest-rest-api.md) · [All operations](https://skmtc.net/pinterest/apis/pinterest-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pinterest/pinterest-rest-api/versions/b698c180678a/schema)