Get keywords
Changed onGet 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."
]
}
]
}
Request
- Base URLhttps://api.pinterest.com/v5
- Auth
- OAuth 2Authorization codehttps://www.pinterest.com/oauth/Token URLhttps://api.pinterest.com/v5/oauth/tokenScopesads:read
- or OAuth 2Client credentialsToken URLhttps://api.pinterest.com/v3/oauth/access_token/Scopesads:read
- TypeScriptA function with typed inputs. Its response is checked against the schema.
Path parameters
Unique identifier of an ad account.
Query parameters
Campaign Id to use to filter the results.
Ad group Id.
List of Ad group Ids to retrieve keywords from. This feature is currently in BETA and is not available to all users.
Keyword match type
[ "BROAD" ]
Cursor used to fetch the next page of items
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"
}
]
}Changes
- breaking
the response's body type changed from no type to
objectfor status - warning
for the
queryrequest parameterpage_size, the max was set to250.00 - info
removed
subschema #2from the response bodyallOflist for the response status - info
added the non-success response with the status
- info
added the non-success response with the status
- info
added the non-success response with the status
- info
added the non-success response with the status
- info
added the non-success response with the status
- info
added the optional property
to the response with the status - info
added the required property
to the response with the status
- breaking
- info
added the new optional
queryrequest parameterad_group_ids
- info