Labels

Amazon Ads API v1 - unified Labels endpoints

Documentation: https://advertising.amazon.com/API/docs/en-us/api-spec-v1-labels Specification: https://d1y2lf8k3vrkfu.cloudfront.net/openapi/en-us/dest/AmazonAdsAPIALLLabelsContract_prod_3p.json

Labels has a single route and it is read only: the contract declares no create, update or delete.

POST /adsApi/v1/query/labels

The required member is not the adProductFilter the other v1 families carry, but labelObjectTypeFilter, and it takes exactly one value:

AD_GROUP, CAMPAIGN, DEAL, INVENTORY_GROUP

A body without it is a rejected request rather than an empty answer, so every call needs that member even when the other filters are left out.

The remaining filters are all optional, and each takes its own list:

adProductFilter exactly one AdProduct labelIdFilter 1 to 50 ids labelNameFilter 1 to 10 names maxResults 1 to 1000, default 100

Warning

DEAL and INVENTORY_GROUP are deal-domain object types. A Sponsored Ads seller profile answers 401 on the deal domain, the same way it does on the DSP families, so only CAMPAIGN and AD_GROUP can be exercised here.

Warning

The route answers 401 Unauthorized with Customer <account> is not authorized to access account on a Sponsored Ads seller profile, even though campaign_view is declared as sufficient. The sibling families that do answer with the same permission (campaigns, ad groups, ads, targets) suggest the family itself is not enabled for such a profile rather than the permission being missing.

The call is built from the contract and verified offline; it has not been exercised against the service from this account.

class ad_api.api.v1.Labels(account='default', marketplace: Marketplaces = Marketplaces.EU, credentials=None, debug=False)

Amazon Ads API v1 - unified Labels endpoints

Labels has a single route and it is read only: there is no create, update or delete in the contract.

The required member is not the usual adProductFilter but labelObjectTypeFilter, and it takes exactly one value:

AD_GROUP, CAMPAIGN, DEAL, INVENTORY_GROUP

adProductFilter is optional here and also takes exactly one value.

query_labels(body: dict) → ApiResponse

Amazon Ads API v1 - Query Labels (operationId: QueryLabel)

Request Body [Required]

labelObjectTypeFilter (dict) : [required] exactly one value | include (list<LabelObjectType>) : Enum [ AD_GROUP, CAMPAIGN, DEAL, INVENTORY_GROUP ]

adProductFilter (dict) : [optional] exactly one value | include (list<AdProduct>) : Enum [ AMAZON_DSP, SPONSORED_BRANDS, SPONSORED_DISPLAY, SPONSORED_PRODUCTS, SPONSORED_TELEVISION ]

labelIdFilter (dict) : [optional] 1..50 ids | include (list<string>)

labelNameFilter (dict) : [optional] 1..10 names | include (list<string>)

maxResults (int) : 1..1000, default 100

nextToken (string) : token to navigate to the next page

Returns

labels (list<Label>) : 0..1000 | labelId (string) : [required] | labelName (string) : [required] | adProduct (AdProduct)

nextToken (string)

A body without labelObjectTypeFilter is a rejected request, not an empty answer, so every call needs that member even when the other filters are left out.

Requires one of these permissions:

campaign_edit, campaign_view