Detailed Targeting

With Targeting Search, you can find targeting with one targeting type in a single API call. With the Detailed Targeting API, you can search for multiple targeting types in a single request at the same time. You can also get suggestions based on your query.

The API has four endpoints: Search, Suggestions, Browse, and Validation.

The response for these endpoints contains the following:

Name	Description
`id` type: string	Target audience ID
`name` type: string	Name of the target audience
`audience_size_lower_bound` integer	Estimated lower bound target audience size
`audience_size_upper_bound` integer	Estimated upper bound target audience size
`path` type: array of strings	Includes the category and any parent categories the targeting falls into
`description` type: string	A short description about target audience

If you do not provide limit_type, we filter results with less than 2000 people into four categories: work_employers, work_positions, education_majors, education_schools. Otherwise you get less meaningful results. When you use limit_type we filter for one of those four categories and will not return everything.

Search

Retrieve target audiences for your ads that match your search query. You can provide the following parameters at this endpoint:

curl -G \
-d "q=harvard" \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/targetingsearch

Name Description

Name	Description
`q` type: string	Required. Query string
`limit` type: integer	Optional. Number of results
`limit_type` type: string	Optional. Limit the type of audience to retrieve. Default to all types
`locale` type: string	Optional. The locale to display audience names and descriptions, if available. Default to ad account's locale

q

type: string

Required.

Query string

limit

type: integer

Optional.

Number of results

limit_type

type: string

Optional.

Limit the type of audience to retrieve. Default to all types

locale

type: string

Optional.

The locale to display audience names and descriptions, if available. Default to ad account's locale

Suggestions

Returns additional audiences you can target based on a few selected audiences you provide.

curl -G \
-d "targeting_list=[{'type':'interests','id':6003119440445}]" \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/targetingsuggestions

Provide these parameters:

Name Description

Name	Description
`targeting_list` type: Array of `{'type':'{TYPE}', 'id':{ID}}`	Required. Array of `{'type':'{TYPE}', 'id':{ID}}` pairs as input audience for suggestions.
`limit` type: integer	Optional. Number of results. Default is 30. Maximum is 45.
`limit_type` type: string	Optional. Limit the type of audience to retrieve. Default to all types
`locale` type: string	Optional. The locale to display audience names and descriptions. Default to ad account's locale

targeting_list

type: Array of {'type':'{TYPE}', 'id':{ID}}

Required.

Array of {'type':'{TYPE}', 'id':{ID}} pairs as input audience for suggestions.

limit

type: integer

Optional.

Number of results. Default is 30. Maximum is 45.

limit_type

type: string

Optional.

Limit the type of audience to retrieve. Default to all types

locale

type: string

Optional.

The locale to display audience names and descriptions. Default to ad account's locale

Browse

Get targeting in a structured taxonomy for Facebook categories, third party data providers and some interests. Results from this endpoint appear in the Browse functionality in Detailed Targeting UI component in Ads Manager.

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/targetingbrowse

Provide the following optional parameters:

Name Description

Name	Description
`limit_type` type: string	Limit the type of audience to retrieve. Default to all types.
`locale` type: string	The locale to display audience names and descriptions. Default to ad account's locale

limit_type

type: string

Limit the type of audience to retrieve. Default to all types.

locale

type: string

The locale to display audience names and descriptions. Default to ad account's locale

Validation

Verify whether an audience is valid for targeting or not. This is helpful if you already created an ad set and want to verify its targeting spec is still valid. If the targeting is not valid, you should delete it from the targeting spec.

curl -G \
-d "targeting_list=[{'type':'interests','id':6003283735711}, {'type':'relationship_statuses','id':100}]" \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/targetingvalidation

In addition to the standard Detailed Targeting response fields, this endpoint also returns:

Name description

Name	description
`valid` type: boolean	Whether the targeting audience is valid or not

valid

type: boolean

Whether the targeting audience is valid or not

Here is the list of input parameters:

Name	Description
`targeting_list` type: Array of `{'type':'{TYPE}', 'id':{ID}}`	Array of `{'type':'{TYPE}', 'id':{ID}}` pairs for validation. Perferred.
`id_list` type: array of strings	Array of IDs for validation. Succeeds only if an ID is uniquely identifiable in our audience database
`name_list` type: array of strings	Array of Strings for validation. Interests only, case insensitive
`locale` type: string	Locale to display audience names and descriptions. Defaults to ad account's locale

Provide at least one of the following: targeting_list, id_list, and name_list.