Campaign Management

Targeting Criteria

GET accounts/:account_id/targeting_criteria

Retrieve details for some or all of the targeting criteria associated with line items under the current account.

Resource URL

https://ads-api.twitter.com/3/accounts/:account_id/targeting_criteria

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
line_item_id
required

Scope the response to just the targeting criteria under the specified line item.

Type: string

Example: 8u94t
count
optional

Specifies the number of records to try and retrieve per distinct request.

Type: int

Default: 200
Min, Max: 1, 1000
cursor
optional

Specifies a cursor to get the next page of results. See Pagination for more information.

Type: string

Example: 8x7v00oow
lang
optional

An ISO-639-1 language code. When passed, an additional localized_name attribute will be returned in the response for objects where a localized name is available.

Type: string

Example: fr
sort_by
optional

Sorts by supported attribute in ascending or descending order. See Sorting for more information.

Type: string

Example: created_at-asc
targeting_criterion_ids
optional

Scope the response to just the desired targeting criteria by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided.

Type: string

Example: dpl3a6
with_deleted
optional

Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false
with_total_count
optional

Include the total_count response attribute.

Note: This parameter will be ignored if cursor is specified.

Note: Requests which include total_count will have lower rate limits, currently set at 200 per 15 minutes.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.twitter.com/3/accounts/18ce54d4x5t/targeting_criteria?line_item_id=8u94t

Example Response

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "line_item_id": "8u94t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "line_item_id": "8u94t",
      "name": "Custom audience targeting",
      "id": "dpl3a6",
      "account_id": "18ce54d4x5t",
      "tailored_audience_expansion": false,
      "created_at": "2017-05-26T03:29:35Z",
      "targeting_value": "249yj",
      "updated_at": "2017-05-26T03:29:35Z",
      "tailored_audience_type": "CRM",
      "deleted": false,
      "targeting_type": "TAILORED_AUDIENCE"
    }
  ]
}

GET accounts/:account_id/targeting_criteria/:targeting_criterion_id

Retrieve a specific targeting criterion associated with the current account.

Resource URL

https://ads-api.twitter.com/3/accounts/:account_id/targeting_criteria/:targeting_criterion_id

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
targeting_criterion_id
required

A reference to the targeting criterion you are operating with in the request.

Type: string

Example: eijd4y
lang
optional

An ISO-639-1 language code. When passed, an additional localized_name attribute will be returned in the response for objects where a localized name is available.

Type: string

Example: fr
with_deleted
optional

Include deleted results in your request.

Type: boolean

Default: false
Possible values: true, false

Example Request

GET https://ads-api.twitter.com/3/accounts/18ce54d4x5t/targeting_criteria/eijd4y

Example Response

{
  "request": {
    "params": {
      "targeting_criterion_id": "eijd4y",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "line_item_id": "619jl",
    "name": "🤖",
    "id": "eijd4y",
    "account_id": "18ce54d4x5t",
    "created_at": "2017-07-06T16:51:04Z",
    "targeting_value": "🤖",
    "updated_at": "2017-07-06T16:51:04Z",
    "deleted": false,
    "targeting_type": "BROAD_KEYWORD"
  }
}

POST accounts/:account_id/targeting_criteria

See the Targeting Options page to find targeting_values for specific targeting types. We recommend that you refresh all data weekly, to ensure that you are working with the latest set of targeting type values. We change values and available targeting criteria from time to time; while the majority of these don’t change often, some do. There is no guarantee that these values will not change.

Use the BROAD_KEYWORD, EXACT_KEYWORD, PHRASE_KEYWORD, or UNORDERED_KEYWORD targeting types with the keywords specified in the targeting_value. Exclude keywords by using the NEGATIVE_EXACT_KEYWORD, NEGATIVE_PHRASE_KEYWORD, or NEGATIVE_UNORDERED_KEYWORD targeting types.

Note: It is only possible to target a single age bucket per line item.

Note: When using targeting type TV_SHOW, there must be at least one LOCATION targeting criterion on the line item prior to setting the TV_SHOW targeting and all LOCATION must be within the same locale as the TV_SHOW being targeted.

Resource URL

https://ads-api.twitter.com/3/accounts/:account_id/targeting_criteria

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
line_item_id
required

A reference to the line item you are operating with in the request.

Type: string

Example: 69ob
targeting_type
required

The type of targeting that will be applied to this line item.

Possible non-keyword-based values include: AGE, DEVICE, EVENT, CAMPAIGN_ENGAGEMENT, CAMPAIGN_ENGAGEMENT_LOOKALIKE, ENGAGEMENT_TYPE, FOLLOWERS_OF_USER, GENDER, INTEREST, LANGUAGE, LIVE_TV_EVENT, LOCATION, NETWORK_ACTIVATION_DURATION_GTE, NETWORK_ACTIVATION_DURATION_LT, NETWORK_OPERATOR, PLATFORM, PLATFORM_VERSION, SIMILAR_TO_FOLLOWERS_OF_USER, TV_SHOW, USER_ENGAGEMENT, USER_ENGAGEMENT_LOOKALIKE, WIFI_ONLY

Note: It is only possible to target a single AGE bucket per line item.

Possible keyword-based values include: BROAD_KEYWORD, EXACT_KEYWORD, NEGATIVE_EXACT_KEYWORD, NEGATIVE_PHRASE_KEYWORD, NEGATIVE_UNORDERED_KEYWORD, PHRASE_KEYWORD, UNORDERED_KEYWORD

Possible tailored audience values include: TAILORED_AUDIENCE

Possible behavior values: BEHAVIOR, BEHAVIOR_EXPANDED, NEGATIVE_BEHAVIOR

Possible installed app store category values: APP_STORE_CATEGORY, APP_STORE_CATEGORY_LOOKALIKE

Possible Twitter Audience Platform (TAP) app blacklisting values: EXCLUDE_APP_LIST
targeting_value
required

Specify which user, which interest, which location, which event, which platform, which platform version, which device, which keyword or phrase, which gender, which tailored audience, which behavior, which app store category, or which exclusion of an app list this targeting will be applied to, depending on the selected targeting_type.

Type: string

Example: 174958347
tailored_audience_expansion
optional

Expand tailored audience reach if using the Tailored Audience CRM.

Note: targeting_type should be set to TAILORED_AUDIENCE

Type: boolean

Default: false
Possible values: true, false
tailored_audience_type
optional

Select a tailored audience type

Type: enum

Possible values: CRM, EXCLUDED_CRM, EXCLUDED_MOBILE, EXCLUDED_WEB, MOBILE, WEB

Example Request

POST https://ads-api.twitter.com/3/accounts/18ce54d4x5t/targeting_criteria?line_item_id=619jl&targeting_type=BROAD_KEYWORD&targeting_value=technology

Example Response

{
  "data": {
    "line_item_id": "619jl",
    "name": "technology",
    "id": "fbyjlr",
    "account_id": "18ce54d4x5t",
    "created_at": "2017-09-06T07:31:21Z",
    "targeting_value": "technology",
    "updated_at": "2017-09-06T07:31:21Z",
    "deleted": false,
    "targeting_type": "BROAD_KEYWORD"
  },
  "request": {
    "params": {
      "line_item_id": "619jl",
      "targeting_type": "BROAD_KEYWORD",
      "targeting_value": "technology",
      "account_id": "18ce54d4x5t"
    }
  }
}

POST batch/accounts/:account_id/targeting_criteria

Allows the batch creation of new Targeting Criteria with a single request.

Batch Requests

  • The current maximum batch size is 500.
  • All parameters are sent in the request body and a Content-Type of application/json is required.
  • Batch requests fail or succeed together as a group and all API responses for both error and success preserve the item order of the initial request.

Batch Responses

Batch API responses return an ordered collection of items. Otherwise, they are identical in structure to their corresponding single-item endpoints.

Batch Errors

  • Request-level errors (eg. max batch size exceeded) are shown in the response under the errors object.
  • Item-level errors (eg. missing required Targeting Criteria parameter) are shown in the response under the operation_errors object.

Resource URL

https://ads-api.twitter.com/3/batch/accounts/:account_id/targeting_criteria

Parameters

Name Description
operation_type
required

The per item operation type being performed.

Type: enum

Possible values: Create, Delete
params
required

A JSON object containing all the parameters for the targeting criteria objects. For a list of required and optional targeting criteria parameters, see here.

In addition, this endpoint supports an operator_type parameter that works in conjunction with certain targeting_type values. The possible values for this parameter are EQ for equal to, GTE for greater than or equal to, LT for less than, and NE for not equal to.

Example Request

POST https://ads-api.twitter.com/3/batch/accounts/18ce54d4x5t/targeting_criteria

[
  {
    "operation_type":"Create",
    "params":{
      "line_item_id":"6f9an",
      "targeting_type":"LOCATION",
      "targeting_value":"5122804691e5fecc"
    }
  },
  {
    "operation_type":"Delete",
    "params":{
      "targeting_criterion_id":"al2rua"
    }
  }
]

Example Response

{
  "data_type": "targeting_criterion",
  "data": [
    {
      "line_item_id": "6f9an",
      "name": "San Francisco-Oakland-San Jose CA, US",
      "id": "al7vt2",
      "location_type": "CITY",
      "operator_type": "EQ",
      "created_at": "2016-11-11T22:59:50Z",
      "targeting_value": "5122804691e5fecc",
      "updated_at": "2016-11-11T22:59:50Z",
      "deleted": false,
      "targeting_type": "LOCATION"
    },
    {
      "line_item_id": "6keuo",
      "name": "accounts",
      "id": "al2rua",
      "operator_type": "EQ",
      "created_at": "2016-11-11T17:50:19Z",
      "targeting_value": "accounts",
      "updated_at": "2016-11-11T22:59:50Z",
      "deleted": true,
      "targeting_type": "BROAD_KEYWORD"
    }
  ],
  "request": [
    {
      "params": {
        "line_item_id": "6f9an",
        "targeting_type": "LOCATION",
        "targeting_value": "5122804691e5fecc",
        "account_id": "18ce54d4x5t"
      },
      "operation_type": "Create"
    },
    {
      "params": {
        "targeting_criterion_id": "al2rua",
        "account_id": "18ce54d4x5t"
      },
      "operation_type": "Delete"
    }
  ]
}

DELETE accounts/:account_id/targeting_criteria/:targeting_criterion_id

Delete the specified targeting criterion belonging to the current account.

Resource URL

https://ads-api.twitter.com/3/accounts/:account_id/targeting_criteria/:targeting_criterion_id

Parameters

Name Description
account_id
required

The identifier for the leveraged account. Appears within the resource’s path and is generally a required parameter for all Advertiser API requests excluding GET accounts. The specified account must be associated with the authenticated user.

Type: string

Example: 18ce54d4x5t
targeting_criterion_id
required

A reference to the targeting criterion you are operating with in the request.

Type: string

Example: dpl3a6

Example Request

DELETE https://ads-api.twitter.com/3/accounts/18ce54d4x5t/targeting_criteria/dpl3a6

Example Response

{
  "data": {
    "line_item_id": "8u94t",
    "name": "Custom audience targeting",
    "id": "dpl3a6",
    "account_id": "18ce54d4x5t",
    "tailored_audience_expansion": false,
    "created_at": "2017-05-26T03:29:35Z",
    "targeting_value": "249yj",
    "updated_at": "2017-08-30T18:38:58Z",
    "tailored_audience_type": "CRM",
    "deleted": true,
    "targeting_type": "TAILORED_AUDIENCE"
  },
  "request": {
    "params": {
      "targeting_criterion_id": "dpl3a6",
      "account_id": "18ce54d4x5t"
    }
  }
}