Campaign Management

Targeting Options

GET targeting_criteria/app_store_categories

Discover available app store category-based targeting criteria for Promoted Products. App store categories are available for the iOS App Store and the Google Play store only.

Installed app category targeting allows targeting of users based on the categories of apps they have installed or have indicated interest in.

Resource URL

https://ads-api.twitter.com/4/targeting_criteria/app_store_categories

Parameters

Name Description
q
optional

An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: music
store
optional

Scope the results by a specific app store.

Type: enum

Possible values: GOOGLE_PLAY, IOS_APP_STORE

Example Request

GET https://ads-api.twitter.com/4/targeting_criteria/app_store_categories?q=music&store=IOS_APP_STORE

Example Response

{
  "data": [
    {
      "name": "Games: Music",
      "targeting_type": "APP_STORE_CATEGORY",
      "targeting_value": "qouq",
      "os_type": "IOS"
    },
    {
      "name": "Music",
      "targeting_type": "APP_STORE_CATEGORY",
      "targeting_value": "qov2",
      "os_type": "IOS"
    }
  ],
  "request": {
    "params": {
      "q": "music",
      "store": "IOS_APP_STORE"
    }
  }
}

GET targeting_criteria/behavior_taxonomies

This endpoint is used to list the full (or partial) structure of behavior taxonomy trees.

When building the complete taxonomy structure in your UI, please ensure you compare the results from the taxonomy against the behaviors obtained via the GET targeting_critertia/behaviors endpoint.

Resource URL

https://ads-api.twitter.com/4/targeting_criteria/behavior_taxonomies

Parameters

Name Description
behavior_taxonomy_ids
optional

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

Type: string

Example: 5e
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
parent_behavior_taxonomy_ids
optional

Scope the response to just the behavior taxonomies under specific parent nodes by specifying a comma-separated list of identifiers. Up to 200 IDs may be provided

Type: string

Example: 2e
sort_by
optional

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

Type: string

Example: created_at-asc
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/4/targeting_criteria/behavior_taxonomies?behavior_taxonomy_ids=5e

Example Response

{
  "data": [
    {
      "name": "Travel services",
      "parent_id": "31",
      "id": "5e",
      "created_at": "2015-01-21T21:51:28Z",
      "updated_at": "2015-01-21T21:51:28Z"
    }
  ],
  "next_cursor": null,
  "request": {
    "params": {
      "behavior_taxonomy_ids": [
        "5e"
      ]
    }
  }
}

GET targeting_criteria/behaviors

Discover available behavior-based targeting criteria for Promoted Products.

Resource URL

https://ads-api.twitter.com/4/targeting_criteria/behaviors

Parameters

Name Description
behavior_ids
optional

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

Type: string

Example: lfrt
count
optional

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

Type: int

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

An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. If this parameter is not specified only partner audiences for the United States are returned.

Type: string

Default: US
cursor
optional

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

Type: string

Example: 8x7v00oow
sort_by
optional

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

Type: string

Example: created_at-asc
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/4/targeting_criteria/behaviors?behavior_ids=lfrt

Example Response

{
  "data": [
    {
      "name": "Auto service buyer",
      "targetable_types": [
        "BEHAVIOR",
        "NEGATIVE_BEHAVIOR",
        "BEHAVIOR_LOOKALIKE_EXPANDED"
      ],
      "country_code": "US",
      "id": "lfrt",
      "partner_source": "Datalogix",
      "behavior_taxonomy_id": "2",
      "audience_size": 9583030
    }
  ],
  "next_cursor": null,
  "request": {
    "params": {
      "behavior_ids": [
        "lfrt"
      ]
    }
  }
}

GET targeting_criteria/devices

Discover available device-based targeting criteria for Promoted Products. Device targeting is available for Promoted Tweets.

Resource URL

https://ads-api.twitter.com/4/targeting_criteria/devices

Parameters

Name Description
count
optional

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

Type: int

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

An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: apple

Example Request

GET https://ads-api.twitter.com/4/targeting_criteria/devices?count=2&q=iphone

Example Response

{
  "data": [
    {
      "name": "iPhone 3GS",
      "manufacturer": "Apple",
      "platform": "iOS",
      "targeting_value": "1q",
      "targeting_type": "DEVICE"
    },
    {
      "name": "iPhone 4",
      "manufacturer": "Apple",
      "platform": "iOS",
      "targeting_value": "1r",
      "targeting_type": "DEVICE"
    }
  ],
  "request": {
    "params": {
      "q": "iphone",
      "count": 2
    }
  }
}

GET targeting_criteria/events

Discover available event-based targeting criteria for Promoted Products. Only one event can be targeted per line item.

Event targeting is currently immutable and not supported on the PUT accounts/:account_id/targeting_criteria endpoint.

Note: Events often exist across timezones, leading to complications when considering event times from cross-timezone perspectives. To simplify this, all event start_time and end_time values on this endpoint are represented in UTC±00:00, irrespective of the event's locale and timezone. This design should be kept in mind when querying and interacting with event start_time and end_time values. For example, Independence Day for the US is represented as start_time=2017-07-04T00:00:00Z and end_time=2017-07-05T00:00:00Z in UTC±00:00, and thus avoids the issue of this holiday existing across multiple timezones within the US.

Resource URL

https://ads-api.twitter.com/4/targeting_criteria/events

Parameters

Name Description
event_types
required

An optional query to scope to certain event types.

Type: enum

Possible values: CONFERENCE, HOLIDAY, MUSIC_AND_ENTERTAINMENT, OTHER, SPORTS
count
optional

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

Type: int

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

An optional query to scope a targeting criteria search to particular countries with the 2 letter ISO country code. If this parameter is not specified only partner audiences for the United States are returned.

Type: string

Default: US
cursor
optional

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

Type: string

Example: 8x7v00oow
end_time
optional

The time, expressed in ISO 8601, that the campaign will end.

Type: string

Example: 2017-10-05T00:00:00Z
ids
optional

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

Type: string

Example: lex
start_time
optional

The time, expressed in ISO 8601, that the line item will begin serving.

Note: Defaults to the current time.

Type: string

Example: 2017-07-05T00:00:00Z

Example Request

GET https://ads-api.twitter.com/4/targeting_criteria/events?ids=lex

Example Response

{
  "request": {
    "params": {
      "ids": [
        "1ex"
      ]
    }
  },
  "data_type": "events",
  "data": [
    {
      "reach": {
        "total_reach": null
      },
      "name": "New Year's",
      "start_time": "2017-12-31T00:00:00Z",
      "top_users": [],
      "top_tweets": [],
      "top_hashtags": [],
      "gender_breakdown_percentage": {},
      "end_time": "2018-01-02T00:00:00Z",
      "country_code": null,
      "device_breakdown_percentage": {},
      "id": "1ex",
      "is_global": true,
      "event_type": "HOLIDAY",
      "country_breakdown_percentage": {}
    }
  ],
  "next_cursor": null
}

GET targeting_criteria/interests

Discover available interest-based targeting criteria for Promoted Products. Interests change infrequently, however we suggest you refresh this list at least once weekly.

Resource URL

https://ads-api.twitter.com/4/targeting_criteria/interests

Parameters

Name Description
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
q
optional

An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: books

Example Request

GET https://ads-api.twitter.com/4/targeting_criteria/interests?q=books

Example Response

{
  "data": [
    {
      "name": "Books and literature/Biographies and memoirs",
      "targeting_type": "INTEREST",
      "targeting_value": "1001"
    }
  ],
  "request": {
    "params": {
      "q": "books",
      "count": 1
    }
  },
  "next_cursor": "6by4n4"
}

GET targeting_criteria/languages

Discover languages available for targeting.

Resource URL

https://ads-api.twitter.com/4/targeting_criteria/languages

Parameters

Name Description
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
q
optional

An optional query to scope a targeting criteria. Omit this parameter to retrive all.

Type: string

Example: english

Example Request

GET https://ads-api.twitter.com/4/targeting_criteria/languages?q=english

Example Response

{
  "data": [
    {
      "name": "English",
      "targeting_type": "LANGUAGE",
      "targeting_value": "en"
    }
  ],
  "request": {
    "params": {
      "q": "english"
    }
  },
  "next_cursor": null
}

GET targeting_criteria/locations

Discover available location-based targeting criteria for Promoted Products. Geo-targeting is available for Promoted Accounts and Promoted Tweets at the country level, state/region level, city level, and postal code level. Postal code targeting must be used if you wish to retrieve analytics at the postal code level.

Note: The location_type enums are now plural. COUNTRY is now COUNTRIES, REGION is now REGIONS, and so on.

Note: Version 2 makes it possible to target specific cities (only for ads accounts that have been granted the CITY_TARGETING account feature), such as San Francisco or New York, using the CITIES enum. In version 1, cities (the CITY enum) referred to Designated Market Areas (DMA) or "metros." To target these metro areas in version 2, use the METROS enum.

Note: City targeting is only available for cities in the US.

Resource URL

https://ads-api.twitter.com/4/targeting_criteria/locations

Parameters

Name Description
count
optional

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

Type: int

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

An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. Omit this parameter to retrieve results for all countries.

Type: string

Example: JP
cursor
optional

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

Type: string

Example: 8x7v00oow
location_type
optional

Scope the results by a specific kind of location. More granular targeting than COUNTRIES may not be available in all locations.

Type: enum

Possible values: COUNTRIES, REGIONS, METROS, CITIES, POSTAL_CODES
q
optional

An optional query to scope a targeting criteria search. Omit this parameter to retrieve all results.

Type: string

Example: New York

Example Request

GET https://ads-api.twitter.com/4/targeting_criteria/locations?location_type=CITIES&q=los angeles

Example Response

{
  "data": [
    {
      "name": "Los Angeles, Los Angeles CA, CA, USA",
      "country_code": "US",
      "location_type": "CITIES",
      "targeting_value": "3b77caf94bfc81fe",
      "targeting_type": "LOCATION"
    },
    {
      "name": "East Los Angeles, Los Angeles CA, CA, USA",
      "country_code": "US",
      "location_type": "CITIES",
      "targeting_value": "67571a7baaa5906b",
      "targeting_type": "LOCATION"
    },
    {
      "name": "Lake Los Angeles, Los Angeles CA, CA, USA",
      "country_code": "US",
      "location_type": "CITIES",
      "targeting_value": "ea9bfbd43c93400f",
      "targeting_type": "LOCATION"
    },
    {
      "name": "Los Gatos, San Francisco-Oakland-San Jose CA, CA, USA",
      "country_code": "US",
      "location_type": "CITIES",
      "targeting_value": "a2de7c70b82b0ca0",
      "targeting_type": "LOCATION"
    },
    {
      "name": "Los Altos, Monterey-Salinas CA, CA, USA",
      "country_code": "US",
      "location_type": "CITIES",
      "targeting_value": "6a4364ea6f987c10",
      "targeting_type": "LOCATION"
    },
    {
      "name": "Los Banos, CA, USA",
      "country_code": "US",
      "location_type": "CITIES",
      "targeting_value": "b1b6fc646de75904",
      "targeting_type": "LOCATION"
    },
    {
      "name": "Los Alamitos, Los Angeles CA, CA, USA",
      "country_code": "US",
      "location_type": "CITIES",
      "targeting_value": "0799ff0a3c1006e9",
      "targeting_type": "LOCATION"
    },
    {
      "name": "Los Angeles, US",
      "country_code": "US",
      "location_type": "CITIES",
      "targeting_value": "019940ae78c7b3bc",
      "targeting_type": "LOCATION"
    }
  ],
  "request": {
    "params": {
      "location_type": "CITIES",
      "q": "los angeles"
    }
  },
  "next_cursor": null
}

GET targeting_criteria/network_operators

Discover available network operator-based targeting criteria for Promoted Products.

This endpoint enables you to lookup targetingable carriers, such as AT&T, Verizon, Sprint, T-Mobile, etc., in multiple countries.

Resource URL

https://ads-api.twitter.com/4/targeting_criteria/network_operators

Parameters

Name Description
count
optional

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

Type: int

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

An optional query to scope a targeting criteria search to a specific country with the 2 letter ISO country code. If this parameter is not specified only partner audiences for the United States are returned.

Type: string

Default: US
cursor
optional

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

Type: string

Example: 8x7v00oow
q
optional

An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.

Type: string

Examples: Airpeak

Example Request

GET https://ads-api.twitter.com/4/targeting_criteria/network_operators?count=5&country_code=US

Example Response

{
  "data": [
    {
      "country_code": "US",
      "targeting_type": "NETWORK_OPERATOR",
      "name": "Advantage",
      "targeting_value": "2l"
    },
    {
      "country_code": "US",
      "targeting_type": "NETWORK_OPERATOR",
      "name": "Aeris",
      "targeting_value": "1b"
    },
    {
      "country_code": "US",
      "targeting_type": "NETWORK_OPERATOR",
      "name": "Airadigm",
      "targeting_value": "2t"
    },
    {
      "country_code": "US",
      "targeting_type": "NETWORK_OPERATOR",
      "name": "Airlink PCS",
      "targeting_value": "14"
    },
    {
      "country_code": "US",
      "targeting_type": "NETWORK_OPERATOR",
      "name": "Airpeak",
      "targeting_value": "1i"
    }
  ],
  "request": {
    "params": {
      "country_code": "US",
      "count": 5
    }
  },
  "next_cursor": "o7x9iet1a5u608olj4"
}

GET targeting_criteria/platform_versions

Discover available mobile OS version-based targeting criteria for Promoted Products. Platform version targeting is available for Promoted Accounts and Promoted Tweets. This allows targeting down to the point release of a mobile operating system version, such as Android 8.0 or iOS 10.0.

Resource URL

https://ads-api.twitter.com/4/targeting_criteria/platform_versions

Parameters

Name Description
q
optional

An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.

Type: string

Examples: jelly bean

Example Request

GET https://ads-api.twitter.com/4/targeting_criteria/platform_versions

Example Response

{
    "data": [
        {...},
        {
            "name": "Ice Cream Sandwich",
            "number": "4.0",
            "platform": "Android",
            "targeting_type": "PLATFORM_VERSION",
            "targeting_value": "17"
        },
        {
            "name": "Jelly Bean",
            "number": "4.1",
            "platform": "Android",
            "targeting_type": "PLATFORM_VERSION",
            "targeting_value": "18"
        },
        {...}
    ],
    "data_type": "targeting_criterion",
    "request": {
        "params": {}
    }
}

GET targeting_criteria/platforms

Discover available platform-based targeting criteria for Promoted Products.

Resource URL

https://ads-api.twitter.com/4/targeting_criteria/platforms

Parameters

Name Description
count
optional

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

Type: int

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

An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.

Type: string

Examples: ios, blackberry
lang
optional

Using a ISO-639-1 language code. When passed, an additional localized_name attribute will be returned in the response.

Type: int, string

Example: fr

Example Request

GET https://ads-api.twitter.com/4/targeting_criteria/platforms

Example Response

{
  "data": [
    {
      "name": "iOS",
      "targeting_type": "PLATFORM",
      "targeting_value": "0"
    },
    {
      "name": "Android",
      "targeting_type": "PLATFORM",
      "targeting_value": "1"
    },
    {
      "name": "BlackBerry phones and tablets",
      "targeting_type": "PLATFORM",
      "targeting_value": "2"
    },
    {
      "name": "Mobile web on other devices",
      "targeting_type": "PLATFORM",
      "targeting_value": "3"
    },
    {
      "name": "Desktop and laptop computers",
      "targeting_type": "PLATFORM",
      "targeting_value": "4"
    }
  ],
  "request": {
    "params": {}
  }
}

GET targeting_criteria/tv_markets

Discover available TV markets where TV shows can be targeted. Returns markets by locale that can used to query the GET targeting_criteria/tv_shows endpoint.

Resource URL

https://ads-api.twitter.com/4/targeting_criteria/tv_markets

Parameters

None

Example Request

GET https://ads-api.twitter.com/4/targeting_criteria/tv_markets

Example Response

{
  "data": [
    {
      "id": "6",
      "name": "France",
      "country_code": "FR",
      "locale": "fr-FR"
    },
    {
      "id": "i",
      "name": "Chile",
      "country_code": "CL",
      "locale": "es-CL"
    },
    {
      "id": "a",
      "name": "Germany",
      "country_code": "DE",
      "locale": "de-DE"
    },
    {
      "id": "p",
      "name": "Netherlands",
      "country_code": "NL",
      "locale": "nl-NL"
    },
    {
      "id": "1",
      "name": "United States",
      "country_code": "US",
      "locale": "en-US"
    },
    {
      "id": "k",
      "name": "Venezuela",
      "country_code": "VE",
      "locale": "es-VE"
    },
    {
      "id": "5",
      "name": "Brazil",
      "country_code": "BR",
      "locale": "pt-BR"
    },
    {
      "id": "d",
      "name": "Mexico",
      "country_code": "MX",
      "locale": "es-MX"
    },
    {
      "id": "g",
      "name": "Colombia",
      "country_code": "CO",
      "locale": "es-CO"
    },
    {
      "id": "2",
      "name": "United Kingdom",
      "country_code": "GB",
      "locale": "en-GB"
    },
    {
      "id": "c",
      "name": "Argentina",
      "country_code": "AR",
      "locale": "es-AR"
    },
    {
      "id": "9",
      "name": "Japan",
      "country_code": "JP",
      "locale": "ja-JP"
    },
    {
      "id": "3",
      "name": "Canada",
      "country_code": "CA",
      "locale": "en-CA"
    },
    {
      "id": "7",
      "name": "Spain",
      "country_code": "ES",
      "locale": "es-ES"
    },
    {
      "id": "b",
      "name": "Italy",
      "country_code": "IT",
      "locale": "it-IT"
    },
    {
      "id": "4",
      "name": "United States - Hispanic",
      "country_code": "US",
      "locale": "es-US"
    },
    {
      "id": "f",
      "name": "Ireland",
      "country_code": "IE",
      "locale": "en-IE"
    }
  ],
  "request": {
    "params": {}
  }
}

GET targeting_criteria/tv_shows

Discover available TV show-based targeting criteria for Promoted Products. TV show targeting is available for Promoted Tweets in certain markets. See the GET targeting_criteria/tv_markets endpoint for available markets.

Note: Any audience that contains fewer than 1,000 users will appear with an estimated_users value of 1000.

Note: TV channel and genre targeting options are no longer supported.

Resource URL

https://ads-api.twitter.com/4/targeting_criteria/tv_shows

Parameters

Name Description
tv_market_locale
required

A required parameter that specifies the tv_market_locale to query for available TV shows. TV markets are queried based on locale returned from the GET targeting_criteria/tv_markets.

Type: string

Example: en-US
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
q
optional

An optional query to scope a targeting criteria search. Omit this parameter to this parameter to retrieve all results.

Type: string

Examples: ios, blackberry

Example Request

GET https://ads-api.twitter.com/4/targeting_criteria/tv_shows?tv_market_locale=en-US&q=news&count=1

Example Response

{
  "request": {
    "params": {}
  },
  "data": [
    {
      "name": "BBC World News",
      "id": 10002546242,
      "estimated_users": 1000,
      "genre": "NEWS"
    },
    {
      "name": "E! News",
      "id": 10000283242,
      "estimated_users": 977634,
      "genre": "TALK"
    }
  ],
  "data_type": "targeting_criterion",
  "total_count": 77,
  "next_cursor": "c-2"
}