Returns retargeting lists.

  1. Restrictions
  2. Request
  3. Response


The method returns a maximum of 10,000 objects.


Request structure in JSON format:

  "method": "get",
  "params": { /* params */
    "SelectionCriteria": {  /* RetargetingListSelectionCriteria */
      "Ids": [(long), ... ]
    "FieldNames": [( "Id" | "Name" | "Description" | "Rules" | "IsAvailable" | "Scope" ), ... ], /* required */
    "Page": {  /* LimitOffset */
      "Limit": (long),
      "Offset": (long)
Parameter Type Description Required
Params structure (for JSON) / GetRequest (for SOAP)
SelectionCriteria RetargetingListSelectionCriteria

Criteria for selecting retargeting lists. If omitted, all retargeting lists that belong to the advertiser are returned.

FieldNames array of RetargetingListFieldEnum Names of top-level parameters to get. Yes
Page LimitOffset

Structure that defines the page for paginated selection of data.

RetargetingListSelectionCriteria structure
Ids array of long Selects the retargeting lists with the specified IDs. From 1 to 10,000 items in the array. No


Response structure in JSON format:

  "result": { /* result */
    "RetargetingLists": [{  /* RetargetingListGetItem */
      "Id": (long),
      "IsAvailable": ( "YES" | "NO" ),
      "Name": (string),
      "Description": (string),
      "Rules": [{ /* RetargetingListRuleItem */
        "Arguments": [{  /* RetargetingListRuleArgumentItem */
          "MembershipLifeSpan": (int), /* required */
          "ExternalId": (long) /* required */
        }, ... ], /* required */
        "Operator": ( "ALL" | "ANY" | "NONE" ) /* required */
      }, ... ],
    }, ... ],
    "LimitedBy": (long)
Parameter Type Description
Result structure (for JSON) / GetResponse (for SOAP)
RetargetingLists array of RetargetingListGetItem Retargeting lists.
LimitedBy long Sequential number of the last object returned. It is included if there was a limit on the number of objects in the response. See the section Paginated data selection.
RetargetingListGetItem structure
Id long ID of the retargeting list.
Name string Name of the retargeting list (maximum of 250 characters).
Description string Text note for the retargeting list (maximum of 4096 characters).
IsAvailable YesNoEnum

YES — All the goals and segments in the retargeting list are available; NO — The retargeting list has a goal or segment that is unavailable, so ad displays and bid adjustments aren't possible for this retargeting list.

A goal or segment becomes unavailable if it is deleted, or if the owner revokes access (see Managing tag access in the Help for Yandex.Metrica).

Rules array of RetargetingListRuleItem Rules for selecting site users. Maximum of 50 items in the array. In order for the retargeting list to apply, the user must meet all the rules at once.
Scope RetargetingListScopeEnum

Scope of the retargeting list. See the section Scope.

RetargetingListRuleItem structure
Arguments array of RetargetingListRuleArgumentItem

Yandex.Metrica goals and segments, or Yandex.Audience segments. Maximum of 250 items in the array.

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

Operator RetargetingListRuleOperatorEnum

Logical operator for the retargeting list:

  • 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.

A retargeting list that uses segments from Yandex.Metrica or Yandex.Audience must contain at leat one rule and the logical operator ALL or ANY. A retargeting list that consists exclusively of rules with the NONE operator can only contain Yandex.Metrica goals.

RetargetingListRuleArgumentItem structure
MembershipLifeSpan int Number of days (from 1 to 90) for checking whether goals are completed or segments are matched.
ExternalId long

ID of the goal or segment.

To get a list of goals and segments available to the advertiser, use the GetRetargetingGoals (Live) method in the Live 4 version of the API.