Fetch Recommendations Details

This API lets you fetch/retrieve the metadata associated with a recommendation using the recommendation ID. The metadata can include the recommendation name, model type, status, creation and update time, and so on.

API Endpoint

Method: GET

API Endpoint
https://api-{{0X}}.moengage.com/v1/recommendations/{{recommendations_id}}

Each customer is hosted on a different data center; you can find your data center number (value of X) by checking the data center and API endpoint mapping page.

Path Parameters

Key Sample Values Description
recommendations_id a1b2c3...
  • This parameter indicates the unique identifier associated with the recommendation created in the recommendation module.
  • You can obtain the recommendation_id from the recommendation you created on the recommendation page.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username: password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"}

You can obtain the username and password details from the MoEngage Dashboard.

  1. Navigate to Settings > Account > APIs.
  2. Copy the following details:
    • Username: Under Workspace ID (earlier App ID), click the copy icon to copy the username.
    • Password: In the API keys section, click the copy icon in the Campaign report/Business events/Custom templates/Catalog API tile to copy the API key.
    • Use these details to authenticate the API requests. 

Request Headers

Key Required Sample Values Description
MOE-APPKEY Required {“MOE-APPKEY”: “Workspace ID”}

This is the workspace ID (earlier APP ID) of your MoEngage workspace. The MOE-APPKEY has to be passed in the request. You can find your MoEngage Workspace ID in the MoEngage Dashboard:

SettingsAccountAPIs > Workspace ID (earlier app id)

For more information, refer to Authentication.

Content-Type Optional {"Content-Type": "application/json"}

Set the Content-Type header to application/json.

Authorization Required {"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"}

This authentication parameter, used for access control, must be passed in the request. For more information on generating the authentication header, refer to Authentication.

Response

Status Key Data Type Description
Success id String It is the unique recommendation ID.
db_name String This is your workspace name.
recommendation_type String

It represents the type of recommendations from which the results will be fetched.

The supported values are:

  • user_action
  • item_attribute
  • similar_item
  • frequently_viewed_together
  • frequently_bought_together
  • trending_item
  • user_personalization
name String This field represents the name of the recommendation for which you want to fetch the details.
description String This field describes the recommendation given at the time of its creation.
catalog String

This is the unique identifier of the catalog assigned to the requested recommendation.

status String The recommendation's status indicates whether it is active or archived.
created_time String This field shows the timestamp when a recommendation was created.
updated_time String This field shows the timestamp when a recommendation setting was last modified.
all_user_actions Boolean

This key represents whether all user actions are being considered to find the most recently interacted item. If this is true, the most recently interacted ID from any of the user action set-ups will be considered to find the related items as per the recommendation type.

Note: This key is available with the similar_item, frequently_viewed_together, and frequently_bought_together recommendation types.

custom_settings JSON

This key defines the customization applied to the recommendation results as per the recommendation setup. Currently, you can apply the user action and item attribute filters over recommendations.

sort JSON

This key defines the sorting logic based on which recommendation results will be ordered. This object's value provides the attributes' details and sorting order.

Note: This key is available with the user_action and item_attribute recommendation types.

trends JSON

This key defines the trend type for trending_item recommendations and the duration of trend computation.

Note: This key is available with the trending_item recommendation type.

Failure error-code String  Each error code is unique and serves as a shorthand representation for the type of error. It provides a quick reference that can be used to diagnose and troubleshoot the problem based on a predefined set of error conditions.
message String With the error code, a detailed message is also provided in the response describing the specifics of the request failure and the nature of the error.
info

Information

The response keys may vary depending on the filters used in the recommendation.

Refer to the Sample Response section for examples

Response Codes

Status Code Request State Description

200

Success

Indicates that the request is successful and a recommendation is fetched.

400

Bad request

Possible issues include a recommendation, the user does not exist, or the wrong format provided.

401

Unauthenticated

Your request is unauthorized. Verify your credentials and try again.

413

Request entity too large

The request body can be large in terms of size (bytes) or length of items.

429

Too Many Requests

There won't be any response body for this request.

500

Internal server error

This response is returned when the system runs into an unexpected error.

Rate Limit

You can fetch 1,000 recommendations per minute.

Sample cURL Request

cURL
curl --location 'https://api-0X.moengage.com/v1/recommendations/{{recommednation_id}}' \
--header 'MOE-APPKEY: {{Workspace_ID and APP_ID}}' \
--header 'Authorization: Basic {{Authorization_Key}}'

Sample Response

200 400 401 413 429 500
{
    "catalog": "Catalog_ID",
    "name": "Catalog_Name",
    "all_user_actions": false,
    "include_filters": {
        "filters": [
            {
                "executed": true,
                "filter_type": "product_filter",
                "operator_fe": "exists",
                "name": "product_id",
                "data_type": "string",
                "operator": "exists",
                "value": "",
                "negate": false,
                "case_sensitive": false,
                "hasError": false
            }
        ],
        "filter_operator": "and"
    },
    "sort": {
        "data_type": "double",
        "param_type": "product_attribute",
        "param": "price",
        "direction": "1"
    },
    "status": "Active",
    "custom_settings": {
        "item_filters": {
            "user_actions": {}
        }
    },
    "db_name": "DB_NAME",
    "created_time": "2024-06-17T10:35:14.978000",
    "updated_time": "2025-01-30T12:07:25.886000",
    "description": "",
    "catalog_name": "Catalog_Name",
    "recommendation_type": "recommendation_type",
    "id": "recommendation_id"
}

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.

Previous

Next

Was this article helpful?
0 out of 0 found this helpful

How can we improve this article?