v29

latestOpenAPI 3.0.3MITraw.githubusercontent.com2026-06-042661,1122.5 MB
keywords

Get keywords

Get a list of keywords based on the filters provided. If no filter is provided, it will default to the `ad_account_id` filter, which means it will only return keywords that specifically have `parent_id` set to the `ad_account_id`. Note: Keywords can have `ad_account_ids`, `campaign_ids`, and `ad_group_ids` set as their `parent_ids`. Keywords created through Ads Manager will have their `parent_id` set to an `ad_group_id`, not `ad_account_id`.

For more information, see [Keyword targeting](https://help.pinterest.com/en/business/article/keyword-targeting).

**Notes:**
- Advertisers and campaigns can only be assigned keywords with excluding (`_NEGATIVE`).
- All keyword match types are available for ad groups.

For more information on match types, see [match type enums](/docs/api-features/targeting-overview/).

**Returns:**
- A successful call returns an object containing an array of new keyword objects and an empty `errors` object array.
- An unsuccessful call returns an empty keywords array, and instead, inserts the entire object with nulled/negated properties into the `errors` object array:
  ```json
  {
    "keywords": [],
    "errors": [
      {
        "data": {
          "archived": null,
          "match_type": "EXACT",
          "parent_type": null,
          "value": "foobar",
          "parent_id": null,
          "type": "keyword",
          "id": null
        },
        "error_messages": [
          "Advertisers and Campaigns only accept excluded targeting attributes."
        ]
      }
    ]
  }
get/ad_accounts/{ad_account_id}/keywords

Path parameters

ad_account_idstring required

Unique identifier of an ad account.

Query parameters

campaign_idstring

Campaign Id to use to filter the results.

ad_group_idstring

Ad group Id.

ad_group_idsPinterestLibIntegerFormatType[]

List of Ad group Ids to retrieve keywords from. This feature is currently in BETA and is not available to all users.

match_typesMatchType[]

Keyword match type

[
  "BROAD"
]
bookmarkstring

Cursor used to fetch the next page of items

page_sizeinteger

Maximum number of items to include in a single page. See documentation on Pagination for more information.

Response

The request has succeeded.

bookmarkstring nullable

Example response

{
  "items": [
    {
      "id": "383791336903426391",
      "match_type": "BROAD",
      "parent_id": "383791336903426391",
      "parent_type": "campaign",
      "type": "keyword"
    }
  ]
}