Models API Overview

The Models API, also called the Blocklist API, enables users to view and manage the list of features used in machine learning models for Automated Personalization (AP) and Auto-Target (AT) activities. If a user would like to exclude a feature from being used by the models for AP or AT activities, they can use the Models API to add that feature to the “blocklist.”

A blocklist defines the set of features that will be excluded by Adobe Target from its machine learning models. For more information on features, see Data used by Target machine-learning algorithms.

Blocklists may be defined per activity (activity level), or for all activities within a Target account (global level).

Models API specification

View the Models API specification here.

Prerequisites

To use the Models API, you must configure authentication using the Adobe Developer Console, just as you would with the Target Admin API. For more information, see How to Configure Authentication.

Models API usage guidelines

How to manage blocklists

Step 1: View list of features for an activity

Step 2: Check the blocklist of the activity

Step 3: Add features to the blocklist of the activity

Step 4: (Optional) Unblock

Step 5: (Optional) Manage the global blocklist

Step 1: View list of features for an activity step1

Before blocklisting a feature, view the list of features that are currently being included in the models for that activity.

GET https://mc.adobe.io/<tenant>/target/models/features/<campaignId>

{
    "features": [
        {
            "externalName": "Visitor Profile - Total Visits to Activity",
            "internalName": "SES_PREVIOUS_VISIT_COUNT",
            "type": "CONTINUOUS"
        },
        {
            "externalName": "Visitor Profile - Total Visits",
            "internalName": "SES_TOTAL_SESSIONS",
            "type": "CONTINUOUS"
        },
        {
            "externalName": "Visitor Profile - Pages Seen Before Activity",
            "internalName": "SES_PREVIOUS_VISIT_COUNT",
            "type": "CONTINUOUS"
        },
        {
            "externalName": "Visitor Profile - Activity Lifetime Time on Site",
            "internalName": "SES_TOTAL_TIME",
            "type": "CONTINUOUS"
        }
    ],
    "reportParameters": {
        "clientCode": <tenant>,
        "campaignId": <campaignId>
    }
}

In the example shown here, the user is checking to see the list of features being used in the model for the activity whose Activity ID is 260840.

The externalName is a user-friendly name for a feature. It is created by Target, and it is possible this value may change over time. Users can view these user-friendly names in the Personalization Insights report.

The internalName is the feature’s actual identifier. It is also created by Target, but it cannot be changed. This is the value you will need to reference in order to identify the feature(s) you would like to blocklist.

Note that in order for the features list to populate with values (that is, in order for it to be non-null), an activity:

Step 2: Check the blocklist of the activity step2

Next, view the blocklist. In other words, check to see which features, if any, are currently being blocked from inclusion in the models for this activity.

GET https://mc.adobe.io/<tenant>/target/models/features/blockList/<campaignId>

In the example shown here, the user is checking the list of blocked features for the activity whose Activity ID is 260840. The results are empty, which means this activity does not currently have any blocklisted features.

Step 3: Add features to the blocklist of the activity step3

To add features to the blocklist, change the request from GET to PUT, and modify the body of the request to specify the blockedFeatureSources or blockedFeatures as desired.

Note that blockedFeatureSources indicates where a feature came from. For the purposes of blocklisting, they serve as groups or categories of features, which enable users to block entire sets of features at once. The values of blockedFeatureSources match the first characters of a feature’s identifier (blockedFeatures or internalName values); therefore they may also be considered “feature prefixes.”

Table of blockedFeatureSources values table

PUT https://mc.adobe.io/<tenant>/target/models/features/blockList/<campaignId>

{
    "blockedFeatureSources": ["AAM"],
    "blockedFeatures": ["SES_PREVIOUS_VISIT_COUNT", "SES_TOTAL_SESSIONS"]
}

{
    "blockedFeatures": [
            "SES_PREVIOUS_VISIT_COUNT",
            "SES_TOTAL_SESSIONS"
        ],
    "blockedFeatureSources": [
            "AAM"
        ]
}

In the example shown here, the user is blocking two features, SES_PREVIOUS_VISIT_COUNT and SES_TOTAL_SESSIONS, which they previously identified by querying the full list of features for the activity whose Activity ID is 260480, as described in Step 1. They are also blocking all features coming from Experience Cloud Segments, which is achieved by blocking features with the prefix of “AAM,” as described in the table above.

Note that after blocklisting a feature, it is recommended that you verify the updated blocklist by performing Step 2 again (GET the blocklist). Verify that the results appear as expected (verify that the results include the features added from the latest PUT request).

Step 4: (Optional) Unblock step4

To unblock all blocklisted features, clear the values from blockedFeatureSources or blockedFeatures.

PUT https://mc.adobe.io/<tenant>/target/models/features/blockList/<campaignId>

{
    "blockedFeatureSources": [],
    "blockedFeatures": []
}

{
    "blockedFeatures": [],
    "blockedFeatureSources": []
}

In the example shown here, the user is clearing their blocklist for the activity whose Activity ID is 260840. Note that the response confirms empty arrays for both blocked features and their sources—blockedFeatureSources and blockedFeatures, respectively.

As always, after modifying the blocklist, it is recommended that you perform Step 2 again (GET the blocklist to verify the list includes features as expected). In the example shown here, the user is verifying that their blocklist is now empty.

Question: How can I delete some, but not all, of a blocklist?

Answer: To remove a discrete subset of blocklisted features from a multi-feature blocklist, users can simply send the updated list of features they would like to block in the blocklist request, as opposed to clearing the entire blocklist and re-adding the desired features. In other words, send the updated feature list (as shown in Step 3), making sure to exclude the features you wish to “delete” from the blocklist.

Step 5: (Optional) Manage the global blocklist step5

The examples above were all in the context of a single activity. You may also block features for all activities across a given client (tenant), instead of having to specify the blocklist for each activity individually. To perform a global blocklist, use the /blockList/global call, instead of blockList/<campaignId>.

PUT https://mc.adobe.io/<tenant>/target/models/features/blockList/global

{
    "blockedFeatureSources": ["AAM", "PRO", "ENV"],
    "blockedFeatures": ["AAM_FEATURE_1", "AAM_FEATURE_2"]
}

{
    "blockedFeatures": [
        "AAM_FEATURE_1",
        "AAM_FEATURE_2"
    ],
    "blockedFeatureSources": [
        "AAM",
        "PRO",
        "ENV"
    ]
}

In the sample Request shown above, the user is blocking two features, “AAM_FEATURE_1” and “AAM_FEATURE_2,” for all activities in their Target account. This means that, regardless of the activity, “AAM_FEATURE_1” and “AAM_FEATURE_2” will not be included in the machine learning models for this account. Furthermore, the user is also globally blocking all features whose prefix is “AAM,” “PRO,” or “ENV.”

Question: Isn’t the code sample above, redundant?

Answer: Yes. It is redundant to block features with values beginning with “AAM,” while also blocking all features whose source is “AAM.” The net result is that all features sourced from AAM (Experience Cloud Segments) will be blocked. Therefore, if the goal is to block all features from Experience Cloud Segments, individually specifying certain features beginning with “AAM” is unnecessary, in the example above.

Final step: Whether at the activity- or global-level, it is recommended that you verify your blocklist after modifying it, to ensure it contains the values you expect. Do this by changing the PUT to a GET.

The sample response shown below indicates Target is blocking two individual features, plus all features sourced from “AAM,” “PRO,” and “ENV.”