Retargeting list (RetargetingList)

A retargeting list defines the criteria for selecting users. Retargeting lists are used in audience targets (see the section Audience targets (AudienceTarget)) and in bid adjustments (see the section Bid adjustments (BidModifier)).

Restrictions

Maximum of 2,000 retargeting lists per advertiser.

Goals and segments

To set up a retargeting list, you can use:

  • Goals and segments configured in Yandex.Metrica: see the section What are goals? Types of goals and section Data segmentation in the Help for Yandex.Metrica and section Retargeting & Audiences in the Help for Yandex.Direct.
  • Segments configured in Yandex.Audience: see the Help for Yandex.Audience.
  • Segments based on Crypta data (demographic and behavior-based segments along with user interest segments): see the section User profile in the Help for Yandex.Direct.

To get a list of available goals and segments from Yandex.Metrica and segments from Yandex.Audience, use the GetRetargetingGoals (Live) method in the Live 4 version of the API.

To get a list of segments based on Crypta data, use the Dictionaries.get method:

  • To get the list of demographic and behavior-based segments, specify the AudienceDemographicProfiles list name in the request. To get the list of demographic and behavioral characteristics, specify AudienceCriteriaTypes.
  • To get the list of user interest segments, specify the AudienceInterests list name in the request.

Type of retargeting lists

The type of a retargeting list is set when creating it and can't be changed.

The following types of retargeting lists are currently available:

  • RETARGETING — A retargeting list may contain goals and segments from Yandex.Metrica and segments from Yandex.Audience. Can be used in the “Text & Image Ads” and “Ads for mobile apps” types of campaigns.
  • AUDIENCE — A retargeting list may contain any types of goals and segments. Can be used in the “Display campaign” type of campaigns.

Rules for user selection

A retargeting list contains rules for user selection (the Rules array) that are combined using the AND principle, meaning the retargeting list applies to users who meet all of the rules.

Each selection rule contains a list of goals or segments (the Arguments array) and the logical operator (the Operator parameter):

  • ALL — The rule is met if the user completed all the goals and is included in all the segments.

  • ANY — The rule is met if the user completed at least one of the goals or the user's session is included in at least one of the segments.

  • NONE — The rule is met if the user didn't complete any of the goals and the user's session isn't included in any of the segments.

Example of the structure:
Restrictions
  • A retargeting list that uses segments from Yandex.Metrica or Yandex.Audience must contain at least one rule with the logical operator ALL or ANY.

    A retargeting list that consists exclusively of rules with the NONE operator can only contain Yandex.Metrica goals.

  • Retargeting lists may contain from 1 to 50 selection rules.

    A selection rule may contain from 1 to 250 goals or segments.

Scope

The scope of a retargeting list of the RETARGETING type depends on which kinds of rules it has:

  • FOR_TARGETS_AND_ADJUSTMENTS

    If a retargeting list of the RETARGETING type contains at least one rule with the ALL or ANY operator, it can be applied both in bid adjustments and in audience targets.

    This type of retargeting list can use goals and segments from Yandex.Metrica and segments from Yandex.Audience.

  • FOR_ADJUSTMENTS_ONLY

    If a retargeting list consists exclusively of rules with the NONE operator, it can only be used in bid adjustments.

    This type of retargeting list can only use Yandex.Metrica goals. Segments from Yandex.Metrica and Yandex.Audience are not allowed.

Changing the scope is not allowed.
  • If you modify a retargeting list that contains at least one rule with the ALL or ANY operator, it still must contain at least one rule with the ALL or ANY operator after your changes.

  • If you modify a retargeting list that consists exclusively of rules with the NONE operator, it must still contain only rules with the NONE operator after your changes.

Otherwise, the edit operation isn't performed, and an error is returned.