Retargeting list (RetargetingList)

Use the RetargetingLists service for managing retargeting lists.

Maximum of 2,000 retargeting lists per advertiser.

To set up a retargeting list, you can use:

• Goals and segments configured in Yandex Metrica: see 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 Yandex Metrica goals, Yandex Metrica segments, and Yandex Audience segments, 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.

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 Yandex Metrica goals, Yandex Metrica segments, and Yandex Audience segments. 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. It can be used in the “Display campaign” type of campaigns. A retargeting list that consists of just a selection rule based on short-term interest segments can also be used in “Text & Image Ads” campaigns.

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:

• For retargeting lists of the RETARGETING type
• For retargeting lists of the AUDIENCE type

Restrictions

• For retargeting lists of the RETARGETING type
• For retargeting lists of the AUDIENCE type

• Retargeting lists may contain from 1 to 50 selection rules based on Yandex Metrica goals, Yandex Metrica segments, and Yandex Audience segments.
• A selection rule may contain from 1 to 250 goals or segments.

• A retargeting list must contain at least one rule with the logical operator ALL or ANY.
• Each selection rule may contain either Yandex Metrica goals, Yandex Metrica segments, and Yandex Audience segments, or demographic segments, or behavior-based segments, or user interest segments.
• For selection rules based on demographic or behavior-based segments:

  • Each selection rule can only contain segments based on a single characteristic or a single behavior (the Type field returned by the Dictionaries.get method in the AudienceDemographicProfiles and AudienceCriteriaTypes lists). For example, only segments by revenue.
  • Retargeting lists may contain no more than one selection rule for each demographic characteristic or behavior. For example, no more than one revenue-based selection rule.
  • For some characteristics and behaviors, you can't specify all the segments (the Rule field in the AudienceCriteriaTypes list). For example, the age-based selection rule should not contain all age groups.
  • Only the ANY operator can be used in a selection rule based on a demographic characteristic or behavior.
• For selection rules based on interest segments:

  • Retargeting lists may include no more than three selection rules based on interest segments.
  • A selection rule may contain no more than 10 interests.
  • An interest-based selection rule can only contain segments with the same interest duration (the InterestType field returned by the Dictionaries.get method in the AudienceInterests list). For example, only short-term interests.
  • Only the ANY operator can be used in an interest-based selection rule.
• For selection rules based on goals and segments from Yandex Metrica and Yandex Audience segments:

  • Retargeting lists may contain from 1 to 50 selection rules based on Yandex Metrica goals, Yandex Metrica segments, and Yandex Audience segments.
  • A selection rule may contain from 1 to 250 goals or segments.

The scope of the retargeting list depends on its type and which kinds of selection rules it has.

The AvailableForTargetsInAdGroupTypes and Scopeparameters returned by the RetargetingLists.get method describe the scope of the retargeting list:

• The AvailableForTargetsInAdGroupTypes parameter defines the types of groups that can have an audience target added for the specified retargeting list.
• The Scope parameter defines where the retargeting list can be used: only in audience targets, only in bid adjustments, or everywhere.