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
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... |
|
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.
- Navigate to Settings > Account > APIs.
- 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: Settings > Account > APIs > 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:
|
|
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 --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
{
"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"
}
{
"error-code": "recommendation does not exist",
"message": "Recommendation does not exist or archived. Please check recommendation_id."
}
{
"error-code": "request-unauthenticated",
"message": "Your request is unauthorized. Please verify your credentials and try again."
}
{
"error-code": "payload-size-exceeded",
"message": "Your payload size exceeds the 1MB limit. Please reduce the payload size and try again."
}
The following headers are returned in case of rate-limit breach:
x-ratelimit-limit (integer)- The maximum number of requests that the consumer is permitted to make in a given time window.
x-ratelimit-remaining (integer)- The number of requests remaining in the current rate limit window.
x-ratelimit-reset (integer)- The time at which the current rate limit window resets in UTC epoch seconds.
{
"error-code": "unexpected-error",
"message": "Something went wrong with your request. Please contact the MoEngage team for further assistance."
}
Postman Collections
We have made it easy for you to test the APIs. Click here to view it in Postman.