Contents

Query Negative Keywords

Query negative keywords using structured filters, sorting, and pagination.

URL

POST https://api.ads.apple.com/v1/negative-keywords/query

Header Parameters

NameTypeDescription
X-AP-Context Requiredstring

Response Codes

StatusReasonTypeDescription
200OK
Content-Type: application/json
NegativeKeywordQueryResponse
400Bad Request
Content-Type: application/json
ErrorResponse
401Unauthorized
Content-Type: application/json
ErrorResponse
403Forbidden
Content-Type: application/json
ErrorResponse
404Not Found
Content-Type: application/json
ErrorResponse
429Too Many Requests
Content-Type: application/json
ErrorResponse
500Internal Server Error
Content-Type: application/json
ErrorResponse

Discussion

This endpoint queries negative keywords using a standard QueryRequest body. The adGroupId field is always required. The API returns an error if it is omitted.

  • The adGroupId EQUALS or adGroupId IN filter scopes the query to one or more specific ad groups. The campaignId field is optional with these operators. The adGroupId IN filter accepts up to 1000 values.

  • The adGroupId IS_NULL filter combined with a campaignId EQUALS filter returns only campaign-level negatives.

  • The adGroupId IS_NOT_NULL filter combined with a campaignId EQUALS filter returns only ad-group-level negatives across the campaign.

  • The adGroupId NOT_EQUALS filter combined with a campaignId EQUALS filter returns ad-group-level negatives, excluding the specified ad group.

  • The campaignId field only supports EQUALS.

  • Filtering by id (EQUALS or IN) is exempt from the adGroupId requirement, since id already fully bounds the query.

The query doesn’t return deleted negative keywords, regardless of any deleted filter. Filtering for deleted EQUALS true or deleted IN [true] returns no records, and deleted IN [true, false] returns only non-deleted records.

See QueryFilterOperator for the full set of supported comparison operators.

Filterable Fields

Field

Type

Operators

Sortable

Description

id

integer

EQUALS, IN

Yes (default)

The unique identifier for the negative keyword.

adGroupId

integer

EQUALS, IN, NOT_EQUALS, IS_NULL, IS_NOT_NULL

Yes

The ad group this negative keyword belongs to. Null if defined at campaign level.

campaignId

integer

EQUALS

Yes

The campaign ID. Negative keywords can be defined at campaign or ad group level.

text

string

EQUALS, STARTS_WITH

The original advertiser-given keyword text.

matchType

string (enum)

EQUALS, IN

Match type for this negative keyword. See Keywordmatchtype.

status

string (enum)

EQUALS, IN

Whether the negative keyword is active or paused. See Negativekeywordstatus.

deleted

boolean

EQUALS

Whether the negative keyword has been deleted. Deleted negative keywords are not returned.

The request body is a QueryRequest composed of QueryFilter conditions and QuerySort directives (QuerySortOrder), controlled by QueryPagination.

Payload Examples

See Also