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.
Example response
{
"items": [
{
"id": "383791336903426391",
"match_type": "BROAD",
"parent_id": "383791336903426391",
"parent_type": "campaign",
"type": "keyword"
}
]
}