---
title: Personalized Site Search Queries
slug: personalized-search/personalized-site-search-queries
description: How to make POST calls to the Monetate Personalized Search API for Personalized Site Search requests
image: https://archbee-image-uploads.s3.amazonaws.com/ceIfEvQHzQk1IVxoRWUh7/K9eTL4jKm7UQINb6zNziJ-20250912-181225.png
docTags:
createdAt: 2024-12-31T20:04:02.771Z
---
When a customer executes a search, or query, it triggers a Personalized Site Search request to identify complete records from your entire storefront that meet the query criteria. The response includes multiple records, representing the search results. Based on the request configuration, each returned record contains data related to a single product, a [product category merchandising page](./#category-page-records-and-personalized-category-page-queries), or a [piece of content published on your site](./#returning-content-page-records).
:::hint{type="info"}
If you've implemented the [Monetate JavaScript API](https://developer.monetate.com/js-api), you can contact your dedicated Customer Success Manager (CSM) to request that custom Personalized Search Results and Personalized Search Suggestions action templates be added to your account so that you can deploy auto-suggestions and site search to your site using a Web experience instead of your own calls to the Personalized Search API. Refer to [Create a Personalized Site Search Experience](https://docs.monetate.com/docs/create-personalized-site-search-experience) for more information.
:::
Refer to [Omnichannel Personalized Search Action Request](docId\:XzJY8yCNDlMWjLE-2oXMw) for the information you must provide in an Engine API request for an Omnichannel experience configured with an [Omnichannel Personalized Search action](https://docs.monetate.com/docs/configure-omnichannel-personalized-search-action).
:::ApiMethodV2
```json
{
"name": "Personalized Site Search Query Request",
"method": "POST",
"url": "https://engine.monetate.net/api/search/v1/site-search/{name}/{instance}/{domain}/search",
"description": "",
"tab": "examples",
"examples": {
"languages": [
{
"id": "t_G5uW_VjFDkhGc0-8sAu",
"language": "json",
"code": "{\n \"searchToken\": \"monetate-156925593843210765\",\n \"recordQueries\": [\n {\n \"id\": \"productSearch\",\n \"typeOfRequest\": \"SEARCH\",\n \"settings\": {\n \"query\": {\n \"term\": \"short\"\n },\n \"limit\": 5,\n \"typeOfRecords\": [\n \"MONETATE_PRODUCT\"\n ],\n \"fields\": [\n \"id\",\n \"name\",\n \"price\"\n ]\n }\n }\n ]\n}",
"customLabel": "Example Personalized Site Search Query Request"
}
],
"selectedLanguageId": "t_G5uW_VjFDkhGc0-8sAu"
},
"results": {
"languages": [
{
"id": "M5iyL778aDWtdmd1ku7o_",
"language": "200",
"customLabel": "",
"code": "{\n \"queryResults\": [\n {\n \"id\": \"productSearch\",\n \"meta\": {\n \"qTime\": 6,\n \"noOfResults\": 5,\n \"totalResultsFound\": 104,\n \"typeOfSearch\": \"WILDCARD_AND\",\n \"offset\": 0,\n \"debuggingInformation\": {},\n \"notificationCode\": 1,\n \"searchedTerm\": \"short\",\n \"searchToken\": \"monetate-156925593843210765\",\n \"isPersonalised\": false\n },\n \"records\": [\n {\n \"price\": \"45.00\",\n \"id\": \"31366431146046\",\n \"name\": \"Erika Running Short\"\n \"searchClickToken\": \"Monetate-NlIsC2LjE2NjIxE3DuMyNzE3MjExOyCd\"\n },\n {\n ... Additional records ...\n }\n ]\n }\n ]\n}"
}
],
"selectedLanguageId": "M5iyL778aDWtdmd1ku7o_"
},
"request": {
"pathParameters": [
{
"name": "name",
"kind": "required",
"type": "string",
"description": "The client's account (for example, \"a-1db61f7a\") as it appears in the value of channel used in the Engine API request to obtain the search token.",
"": "The client's account (for example, \"a-1db61f7a\") as it appears in the value of channel used in the Engine API request to obtain the search token."
},
{
"name": "instance",
"kind": "required",
"type": "string",
"description": "The client's account environment. The value must either be \"p\" for production or \"d\" for development.",
"": "The client's account environment. The value must either be \"p\" for production or \"d\" for development."
},
{
"name": "domain",
"kind": "required",
"type": "string",
"description": "The client's domain (for example, \"product.monetate.me\") as it appears in the value of channel used in the Engine API request to obtain the search token.",
"": "The client's domain (for example, \"product.monetate.me\") as it appears in the value of channel used in the Engine API request to obtain the search token."
}
],
"queryParameters": [],
"headerParameters": [
{
"name": "Content-type",
"kind": "required",
"type": "string",
"description": "The value must be \"application/json.\"",
"": "The value must be \"application/json.\""
}
],
"bodyDataParameters": [
{
"name": "searchToken",
"kind": "required",
"type": "string",
"description": "A token used to authenticate the search request obtained by sending a request to the Engine API. See \"Obtaining a Search Token\" in \"Calling the Personalized Search API\" for more information.",
"": "A token used to authenticate the search request obtained by sending a request to the Engine API. See \"Obtaining a Search Token\" in \"Calling the Personalized Search API\" for more information."
},
{
"name": "recordQueries",
"kind": "required",
"type": "Object",
"description": "The set of parameters that define a Personalized Site Search request.",
"children": [
{
"name": "boost",
"kind": "optional",
"type": "object",
"description": "Query-level aspects to influence the relevancy rankings. Refer to \"Boosting and Burying Results at Run Time\" for more information.",
"children": [
{
"name": "filters",
"kind": "optional",
"type": "object",
"description": "The specific attribute and values that you want Personalized Search to boost or bury in the search results.",
"children": [
{
"name": "key",
"kind": "optional",
"type": "string",
"description": "The unique identifier of the attribute that you want Personalized Search to boost or bury."
},
{
"name": "values",
"kind": "optional",
"type": "array",
"description": "One or more values of an attribute that you want Personalized Search to boost or bury."
},
{
"name": "weight",
"kind": "optional",
"type": "number",
"description": "A numeral representing how much you want Personalized Search to boost or bury the records matching the other key-value pairs in the filters object. For each product you can boost the score up to 999, or lower it anywhere from –1 to –999. A score greater than 1 boosts the product in search results, causing it to appear higher. A negative score buries the product, causing it to appear lower."
}
]
}
]
},
{
"name": "id",
"kind": "required",
"type": "string",
"description": "The unique identifier associated with the request."
},
{
"name": "typeOfRequest",
"kind": "required",
"type": "string",
"description": "The type of query request. Use \"SEARCH\" for the value."
},
{
"name": "settings",
"kind": "required",
"type": "object",
"description": "The set of key-value pairs that define the settings used for search results.",
"children": [
{
"name": "query",
"kind": "required",
"type": "object",
"description": "The set of key-value pairs that define the search term the customer input.",
"children": [
{
"name": "term",
"kind": "required",
"type": "string",
"description": "The search term the customer input."
}
]
},
{
"name": "fields",
"kind": "optional",
"type": "array",
"description": "The collection of product catalog attribute values that you want retrieved (for example, id, name, price). Refer to \"Using the fields Array\" for more information."
},
{
"name": "typeOfSearch",
"kind": "optional",
"type": "string",
"description": "The method that Personalized Search uses to find matches for a customer's search term. Refer to \"Specifying a Search Method\" for possible values."
},
{
"name": "limit",
"kind": "optional",
"type": "number",
"description": "The number of records you want displayed per results page. If you don't pass this key in the request, then Personalized Search uses the default value of 12.\n\nYou can fetch a maximum of 100 records when you pass the limit key. To get more than 100 records, you must define the fields array in the request call."
},
{
"name": "typeOfRecords",
"kind": "required",
"type": "array",
"description": "The type of results to return. Use \"MONETATE_PRODUCT\" for the value when you want Personalized Search to return products. When you want Personalized Search to return content published on your site, use \"MONETATE_CMS\", \"MONETATE_CATEGORY\", or a custom value of the category attribute passed in a mapped Content Pages dataset. Refer to \"Returning Content Page Records\" for more information."
},
{
"name": "sort",
"kind": "optional",
"type": "string",
"description": "The method by which the results are ordered. Refer to \"Sorting Results\" for the possible values."
},
{
"name": "fallbackQueryId",
"kind": "optional",
"type": "string",
"description": "The ID of another query to be fired if the current query yields too few results. Refer to \"Including Fallback Queries\" for more information."
},
{
"name": "fallbackWhenCountLessThan",
"kind": "optional",
"type": "integer",
"description": "The minimum number of results that the initial query must return to prevent the fallback query from returning its own results. Refer to \"Including Fallback Queries\" for more information."
}
]
},
{
"name": "isFallbackQuery",
"kind": "optional",
"type": "boolean",
"description": "Used only with the fallback query. Refer to \"Including Fallback Queries\" for more information.\n\nIf set to true, then Personalized Search triggers the fallback query only when the initial query fails to return enough results to meet the value of fallbackWhenCountLessThan.\n\nIf set to false, then Personalized Search triggers the fallback query even when the initial query returns enough results to meet or exceed the value of fallbackWhenCountLessThan. The default value is false."
}
],
"schema": [
{
"name": "boost",
"kind": "optional",
"type": "object",
"description": "Query-level aspects to influence the relevancy rankings. Refer to \"Boosting and Burying Results at Run Time\" for more information.",
"children": [
{
"name": "filters",
"kind": "optional",
"type": "object",
"description": "The specific attribute and values that you want Personalized Search to boost or bury in the search results.",
"children": [
{
"name": "key",
"kind": "optional",
"type": "string",
"description": "The unique identifier of the attribute that you want Personalized Search to boost or bury."
},
{
"name": "values",
"kind": "optional",
"type": "array",
"description": "One or more values of an attribute that you want Personalized Search to boost or bury."
},
{
"name": "weight",
"kind": "optional",
"type": "number",
"description": "A numeral representing how much you want Personalized Search to boost or bury the records matching the other key-value pairs in the filters object. For each product you can boost the score up to 999, or lower it anywhere from –1 to –999. A score greater than 1 boosts the product in search results, causing it to appear higher. A negative score buries the product, causing it to appear lower."
}
]
}
]
},
{
"name": "id",
"kind": "required",
"type": "string",
"description": "The unique identifier associated with the request."
},
{
"name": "typeOfRequest",
"kind": "required",
"type": "string",
"description": "The type of query request. Use \"SEARCH\" for the value."
},
{
"name": "settings",
"kind": "required",
"type": "object",
"description": "The set of key-value pairs that define the settings used for search results.",
"children": [
{
"name": "query",
"kind": "required",
"type": "object",
"description": "The set of key-value pairs that define the search term the customer input.",
"children": [
{
"name": "term",
"kind": "required",
"type": "string",
"description": "The search term the customer input."
}
]
},
{
"name": "fields",
"kind": "optional",
"type": "array",
"description": "The collection of product catalog attribute values that you want retrieved (for example, id, name, price). Refer to \"Using the fields Array\" for more information."
},
{
"name": "typeOfSearch",
"kind": "optional",
"type": "string",
"description": "The method that Personalized Search uses to find matches for a customer's search term. Refer to \"Specifying a Search Method\" for possible values."
},
{
"name": "limit",
"kind": "optional",
"type": "number",
"description": "The number of records you want displayed per results page. If you don't pass this key in the request, then Personalized Search uses the default value of 12.\n\nYou can fetch a maximum of 100 records when you pass the limit key. To get more than 100 records, you must define the fields array in the request call."
},
{
"name": "typeOfRecords",
"kind": "required",
"type": "array",
"description": "The type of results to return. Use \"MONETATE_PRODUCT\" for the value when you want Personalized Search to return products. When you want Personalized Search to return content published on your site, use \"MONETATE_CMS\", \"MONETATE_CATEGORY\", or a custom value of the category attribute passed in a mapped Content Pages dataset. Refer to \"Returning Content Page Records\" for more information."
},
{
"name": "sort",
"kind": "optional",
"type": "string",
"description": "The method by which the results are ordered. Refer to \"Sorting Results\" for the possible values."
},
{
"name": "fallbackQueryId",
"kind": "optional",
"type": "string",
"description": "The ID of another query to be fired if the current query yields too few results. Refer to \"Including Fallback Queries\" for more information."
},
{
"name": "fallbackWhenCountLessThan",
"kind": "optional",
"type": "integer",
"description": "The minimum number of results that the initial query must return to prevent the fallback query from returning its own results. Refer to \"Including Fallback Queries\" for more information."
}
]
},
{
"name": "isFallbackQuery",
"kind": "optional",
"type": "boolean",
"description": "Used only with the fallback query. Refer to \"Including Fallback Queries\" for more information.\n\nIf set to true, then Personalized Search triggers the fallback query only when the initial query fails to return enough results to meet the value of fallbackWhenCountLessThan.\n\nIf set to false, then Personalized Search triggers the fallback query even when the initial query returns enough results to meet or exceed the value of fallbackWhenCountLessThan. The default value is false."
}
]
}
],
"formDataParameters": []
},
"currentNewParameter": {
"label": "Body Parameter",
"value": "bodyDataParameters"
},
"response": [
{
"name": "id",
"kind": "optional",
"type": "string",
"description": "The ID of the record query for which the results are being returned."
},
{
"name": "meta",
"kind": "optional",
"type": "Object",
"description": "The query-related parameters.",
"children": [
{
"name": "qTime",
"kind": "optional",
"type": "Number",
"description": "The time Personalized Search took to fetch the response."
},
{
"name": "noOfResults",
"kind": "optional",
"type": "Number",
"description": "The number of results requested to be returned for the query."
},
{
"name": "totalResultsFound",
"kind": "optional",
"type": "Number",
"description": "The total results found for the query."
},
{
"name": "typeOfSearch",
"kind": "optional",
"type": "string",
"description": "The search method(s) that Personalized Search used to retrieve the results. Refer to \"Specifying a Search Method\" in this documentation for more information."
},
{
"name": "offset",
"kind": "optional",
"type": "string",
"description": "The index of the first result returned in the response."
},
{
"name": "debuggingInformation",
"kind": "optional",
"type": "string",
"description": "Information that can be useful for debugging the query (for example, the actual query that Personalized Search fired, including any synonyms or de-compounded words taken into consideration)."
},
{
"name": "notificationCode",
"kind": "optional",
"type": "Number",
"description": "A code indicating if any actions were taken on the record. Possible values are as follows:\n\n1 — Nothing to report.\n2 — The price of the record is using the base currency."
},
{
"name": "searchedTerm",
"kind": "optional",
"type": "string",
"description": "The customer's search term submitted for the query."
},
{
"name": "searchToken",
"kind": "optional",
"type": "string",
"description": "The token returned by the decision request to the Engine API sent on page load that contains the relevant information for the experience."
},
{
"name": "isPersonalized",
"kind": "optional",
"type": "Boolean",
"description": "Whether or not customer context was applied to the results."
}
]
},
{
"name": "records",
"kind": "optional",
"type": "Object",
"description": "The records matching the query. Each record object is a map of key-value pairs, where the key is the name of an attribute (for example, id, name, price) and its value in the mapped product catalog.",
"children": [
{
"name": "id",
"kind": "optional",
"type": "string",
"description": "The unique identifier of the record within Personalized Search."
},
{
"name": "itemGroupId",
"kind": "optional",
"type": "string",
"description": "The identifier for a group of products that come in different versions as set in the value of the item_group_id attribute in the mapped product catalog."
},
{
"name": "name",
"kind": "optional",
"type": "string",
"description": "The name of the record (for example, the product name or category title)."
},
{
"name": "url",
"kind": "optional",
"type": "string",
"description": "The fully qualified URL the customer used to access the record on your site."
},
{
"name": "sku",
"kind": "optional",
"type": "string",
"description": "A product's unique identifier as set in the value of the id attribute in the mapped product catalog."
},
{
"name": "inStock",
"kind": "optional",
"type": "string",
"description": "Whether or not the product is in stock. The value is either \"yes\" or \"no.\""
},
{
"name": "price",
"kind": "optional",
"type": "Number",
"description": "The original price of the product, before any discounts as set in the value of the price attribute in the mapped product catalog.\n\nYou can use this parameter as a \"Was [price]\" when used with salePrice."
},
{
"name": "salePrice",
"kind": "optional",
"type": "Number",
"description": "The actual selling price of ther product, or the \"Now [price]\" when used with price. When using filters, the sale price is represented by monetate_price."
},
{
"name": "startPrice",
"kind": "optional",
"type": "Number",
"description": "The value of salePrice for the variant with the lowest price among all variants with the same item group ID. You can use this key-value pair for an \"As low as\" price."
},
{
"name": "toPrice",
"kind": "optional",
"type": "Number",
"description": "The value of salePrice for the variant with the highest price among all variants with the same item group ID. You can use this key-value pair for a \"From X to Y\" price range."
},
{
"name": "groupPrices",
"kind": "optional",
"type": "Number",
"description": "The prices of a record in format groupId:price so that you can use your own front-end logic to display prices in real time. This field isn't always populated, in part because price and salePrice are automatically calculated, so there's no need to use this key-value pair in most cases."
},
{
"name": "currency",
"kind": "optional",
"type": "string",
"description": "The currency code applicable to the price values being displayed."
},
{
"name": "category",
"kind": "optional",
"type": "string",
"description": "A list of a record's most specific categories that excludes the full path, with double semicolons (;;) used to separate them (for example, a record in both Mens > Shoes and Mens > Tees has a value of \"Shoes;;Tees\")."
},
{
"name": "shortDesc",
"kind": "optional",
"type": "string",
"description": "The short description of the record as set in the value of the description attribute in the mapped product catalog."
},
{
"name": "rating",
"kind": "optional",
"type": "Number",
"description": "The product's rating between 0 and 5."
},
{
"name": "ratingCount",
"kind": "optional",
"type": "Number",
"description": "The number of ratings customers have given the product."
},
{
"name": "image",
"kind": "optional",
"type": "string",
"description": "The fully qualified URL to the record's main image."
},
{
"name": "imageHover",
"kind": "optional",
"type": "string",
"description": "The fully qualified URL to the record's secondary image."
},
{
"name": "totalVariants",
"kind": "optional",
"type": "Number",
"description": "The number of variants available for a product in addition to the variant in the search results (for example, a product included in the results for a customer's \"small tshirt\" search has 3 color variants available in size small, so the value of totalVariants is 2; a search for \"tshirt\" would include the same product, but the value of totalVariants is 8 because the product comes in 3 colors, each in 3 sizes)."
},
{
"name": "monetate_manual_boosting",
"kind": "optional",
"type": "Number",
"description": "The Rule Based Merchandising Score (RMS) you set on the Rule-Based Merchandising tab of the Promotions page of the Personalized Search user interface."
},
{
"name": "monetate_product_boosting",
"kind": "optional",
"type": "Number",
"description": "The Product Level Score (PLS) you set on the Product Level Boosting tab of the Promotions page of the Personalized Search user interface."
},
{
"name": "monetate_category",
"kind": "optional",
"type": "string",
"description": "The record's categorization within Personalized Search, with the product name separated from its category hierarchy with double semicolons (;;) and then the category hierarchy itself separated by single semicolons (for example, \"MyBrand Tent;;Sporting Goods;Outdoor Recreation;Camping;Tents\")"
},
{
"name": "brand",
"kind": "optional",
"type": "string",
"description": "The product's brand as set in the value of the brand attribute in the mapped product catalog."
},
{
"name": "typeOfRecord",
"kind": "optional",
"type": "string",
"description": "The record's type (for example, \"MONETATE_PRODUCT\")"
},
{
"name": "additionalDataToReturn",
"kind": "optional",
"type": "string",
"description": "If present for the record, you can use the data to display attribute variations in one product entry on the search results page. Refer to \"Displaying Product Variants\" in \"Preparing to Implement Personalized Search\" in the Monetate Knowledge Base for more information."
},
{
"name": "searchClickToken",
"kind": "optional",
"type": "string",
"description": "A token that contains the relevant information about the customer, about the Omnichannel Personalized Search experience, and about the record the customer clicked."
}
]
}
],
"hasTryItOut": false
}
```
:::
### Using the fields Array
By default, records returned in the response include values for all attributes in the mapped product catalog, including [custom attributes](https://docs.monetate.com/docs/preparing-to-implement-personalized-search#selecting-a-product-catalog). Use the `fields` array to limit the response to the specific attribute values you want returned. Doing so improves response time and decreases response size. As such, you should limit returned attribute values to only those you intend to render.
:::hint{type="info"}
Before you can include one or more custom attributes in the `fields` array of a request, you must first contact your dedicated CSM so that Monetate can enable this option.
:::
## Specifying a Search Method
The value that you can pass in the optional `typeOfSearch` key determines the method(s) that Personalized Search uses to find record matches for a customer's search term. The value options for `typeOfSearch` are as follows:
| **Value** | **Description** |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DEFAULT` | This value prompts Monetate to use a successive order of search methods to find matches. The first method attempted is AND, which means that Monetate must find all the words of a search term exactly as typed in a record to include it in the results. If it finds no results, Monetate then tries the WILDCARD\_AND search method.
The order of search methods used is as follows:
AND
WILDCARD\_AND
FUZZY\_AND
WILDCARD\_OR
FUZZY\_OR
If a search term only contains 1 word or more than 6 words, then Monetate skips the WILDCARD\_OR and FUZZY\_OR search methods. |
| `WILDCARD_AND` | This value dictates that all words of the search term must be found somewhere in a record for Monetate to include it in the results. To bolster the possibility of matches, Monetate appends a wildcard suffix to the last word of the search term (for example, the search term *hooded jacket* becomes *hooded jacket\**, and Monetate then looks for records containing *hooded* **and** any words beginning with *jacket)*. |
| `FUZZY_AND` | This value indicates a search method that is the same as the WILDCARD\_AND query but with a certain amount of fuzziness, or approximate string matching, to account for spelling mistakes (for example, using this query type, Monetate can still match the search term *hooder jakcet* to records containing *hooded* **and** *jacket*). |
| `WILDCARD_OR` | This value indicates an OR search method, so Monetate must find at least 1 of the search term words in a record. To bolster the possibility of matches, Monetate appends a wildcard suffix to the last word of the search term (for example, the search term *hooded jacket* becomes *hooded jacket\**, and Monetate then looks for records containing *hooded* **or** any words beginning with *jacket*). |
| `FUZZY_OR` | This value indicates a search method that is the same as the WILDCARD\_OR search method but with a certain amount of fuzziness, or approximate string matching, to account for spelling mistakes (for example, using this search method, Monetate can still match the search term *hooder jakcet* to records containing *hooded* **or** *jacket*). |
| `AND` | This value indicates that Monetate must find all the words of a search term exactly as typed in a record to include it in the results (for example, with this search method, a search for *hooded jacket* only yields records that contain *hooded* **and** *jacket*). |
| `OR` | This value indicates that Monetate must find at least 1 of the words of a search term exactly as typed in a record to include it in the results (for example, with this search method, a search for *hooded jacket* yields records that contain *hooded* **or** *jacket* **or** *hooded jacket*). |
Here's an example query request with the `FUZZY_OR` search method specified in the `typeOfSearch` key-value pair, along with the response:
:::CodeblockTabs
Example Query Request with Search Method Specified
```json
{
"searchToken": "monetate-156925593843210765",
"recordQueries": [
{
"id": "productSearch",
"typeOfRequest": "SEARCH",
"settings": {
"typeOfSearch": "FUZZY_AND",
"query": {
"term": "hooder jakcet"
},
"limit": 5,
"typeOfRecords": [
"MONETATE_PRODUCT"
],
"fields": [
"id",
"name",
"price"
]
}
}
]
}
```
Response
```json
{
"queryResults": [
{
"id": "productSearch",
"meta": {
"qTime": 6,
"noOfResults": 5,
"totalResultsFound": 104,
"typeOfSearch": "FUZZY_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "hooder jakcet",
"searchToken": "monetate-156925593843210765",
"isPersonalised": false
},
"records": [
{
"price": "95.00",
"id": "31366431146046",
"name": "MyBrand Hooded Jacket"
"searchClickToken": "Monetate-NiRsC2LjE2NjIxT3AuMyNzE3MjExTyJd"
},
{
... Additional records ...
}
]
}
]
}
```
:::
## Including Fallback Queries
While you can present a customer with a "No results found" message when their search term yields no products or other results, you can configure a [query request](docId\:gwGtoOIc_OlMKsSgMarow) that includes a backup that presents the customer with the results from another query that might interest them.
Not only does a fallback query present the customer with results in lieu of a "No results found" message, it doesn't require additional HTTP requests. Furthermore, the fallback query doesn't jeopardize the initial query's performance.
To include a fallback query in a request, add the `fallbackQueryId` key to the initial search query, and use its value to identify the fallback. In a second query in the same request, pass the `id` key with the same value as the value of the `fallbackQueryId` key, the Boolean key `isFallbackQuery` with the value `true`, along with the other required key-value pairs and any optional key-value pairs.
:::hint{type="info"}
You can add the `fallbackQueryId` key-value pair only to the initial search query. You cannot add a fallback query to a fallback query.
:::
Personalized Search triggers the fallback query only when the initial query fails to return the minimum number of results, which you define using the `fallbackWhenCountLessThan` key-value pair. For example, if you want the fallback query to supply results only if the initial query yields fewer than two results, then pass `"fallbackWhenCountLessThan": 3` in the initial query.
If the value of `isFallbackQuery` is `false`, then Personalized Search triggers the fallback query even when the initial query returns enough results to meet or exceed the value of `fallbackWhenCountLessThan`. The results of the fallback query are added to those from the initial query, which could potentially double the number of results.
:::hint{type="info"}
The default value of `isFallbackQuery` is `false`.
:::
Here's an example of a Personalized Site Search request that includes a fallback query along with its response:
:::CodeblockTabs
Example Query Request with Fallback
```json
{
"searchToken": "monetate-156925593843210757",
"recordQueries": [
{
"id": "productList",
"typeOfRequest": "SEARCH",
"settings": {
"query": {
"term": "pickleball shorts"
},
"typeOfSearch": "FUZZY_OR",
"limit": 5,
"typeOfRecords": [
"MONETATE_PRODUCT"
]
"sort": "RELEVANCE",
"fallbackQueryId": "productListFallback",
"fallbackWhenCountLessThan": 3
"fields": [
"id",
"name",
"price"
]
}
},
{
"id": "productListFallback",
"typeOfRequest": "SEARCH",
"isFallbackQuery": "true",
"settings": {
"query": {
"term": "short"
},
"typeOfSearch": "AND",
"limit": 5,
"typeOfRecords": [
"MONETATE_PRODUCT"
]
"sort": "RELEVANCE",
"fields": [
"id",
"name",
"price"
]
}
}
]
}
```
Response
```json
{
"queryResults": [
{
"id": "productList",
"meta": {
"qTime": 1386,
"noOfResults": 5,
"totalResultsFound": 0,
"typeOfSearch": "FUZZY_OR",
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "pickleball shorts",
"searchToken": "monetate-156925593843210757",
"isPersonalised": false
},
"records": []
},
{
"id": "productListFallback",
"meta": {
"qTime": 169,
"noOfResults": 5,
"totalResultsFound": 104,
"typeOfSearch": "AND",
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "short",
"searchToken": "monetate-156925593843210757",
"isPersonalised": false
},
"records": [
{
"id": "31366431146046",
"name": "Erika Running Short"
"price": "45.00",
"searchClickToken": "Monetate-NiIsC2LjE2NjIxE3AuMcNzE3MjExIyCd"
},
{
... Additional records ...
}
]
}
]
}
```
:::
## Sorting Results
By default, records are sorted by relevance to the search term. You can specify another order by including the `sort` key-value pair in the `settings` object.
:::CodeblockTabs
Example Query Request with Sorting
```json
{
"searchToken": "monetate-156925593843210765",
"recordQueries": [
{
"id": "productSearch",
"typeOfRequest": "SEARCH",
"settings": {
"query": {
"term": "short"
},
"limit": 5,
"sort": "PRICE_ASC"
"typeOfRecords": [
"MONETATE_PRODUCT"
]
}
}
]
}
```
:::
The value options for `sort` are as follows:
| **Value** | **Description** |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RELEVANCE` | The default sort order, with sorting based on a combination of Personalized Search's machine learning and your merchandising configurations |
| `PRICE_ASC` | Sort by the value of `salePrice` in each record (the value of the `sale_price` attribute in the mapped product catalog) in ascending order, or by the value of `price` if the mapped product catalog doesn't include a sale price |
| `PRICE_DESC` | Sort by the value of `salePrice` in each record (the value of the `sale_price` attribute in the mapped product catalog) in descending order, or by the value of `price` if the mapped product catalog doesn't include a sale price |
| `NAME_ASC` | Sort by the value of `name` in alphabetical order |
| `NAME_DESC` | Sort by the value of `name` in reverse alphabetical order |
| `RATING_ASC` | Sort by the average rating for each result in ascending order, if the mapped product catalog includes rating information |
| `RATING_DESC` | Sort by the average rating for each result in descending order, if the mapped product catalog includes rating information |
| `NEW_ARRIVAL_ASC` | Sort by the date each record was published in ascending order |
| `NEW_ARRIVAL_DESC` | Sort by the date each record was published in descending order |
## Setting Up Pagination
A page of search results contains a number of records up to the `limit` key-value pair specified in the `settings` object. Additional pages containing records beyond that limit can be created by repeating the query request with the `offset` key-value pair.
:::CodeblockTabs
Example Query Request with Offset
```json
{
"searchToken": "monetate-156925593843210765",
"recordQueries": [
{
"id": "productSearch",
"typeOfRequest": "SEARCH",
"settings": {
"query": {
"term": "short"
},
"limit": 5,
"offset": 5,
"typeOfRecords": [
"MONETATE_PRODUCT"
]
}
}
]
}
```
:::
The value of the `offset` key indicates how many records should be skipped. In this example, the returned records are the sixth through tenth matches.
To properly paginate the search results, repeat the request while incrementing the offset in multiple values of the limit. For example, if the limit is `5`, then the offsets in the sequence of requests should be `0`, `5`, `10`, `15`, `20`, and so on.
## Boosting and Burying Results at Run Time
In addition to the [product-level boosting scores](https://docs.monetate.com/docs/personalized-search-boost-bury#product-level-boosting-scores) and [rule-based merchandising scores](https://docs.monetate.com/docs/personalized-search-boost-bury#rule-based-merchandising-scores) that you can set in the Personalized Search user interface to influence search results, you can also boost and bury product records that have a specific product catalog attribute value in the request that you send to Personalized Search.
For example, a retailer wants to boost products in the search results that are available at a customer's preferred store location as indicated by a store ID. The client passes this information to Monetate in the `inStockStores` custom attribute in its mapped product catalog. Therefore, the request must reference that custom attribute along with store ID values as well as a numeric weight that indicates how much to boost the products with one of the store IDs in the response.
### Prerequisites
Before you can send a Personalized Search API request that includes parameters to boost or bury product records, you must ensure the following about the product catalog attribute(s) that you plan to use for the boosting or burying:
- Monetate has enabled the attribute to serve as a facet.
- The attribute has been disabled as a search results filter option on the **Facets** tab of the Personalized Search Customizations page.
Refer to [Search Results Customizations](https://docs.monetate.com/docs/personalized-search-customizations#customizing-facets) in the Monetate Knowledge Base for more information about viewing enabled attributes and disabling them as facets.
In some use cases, you may need to ensure that the attribute's data type is defined in the product catalog schema as `MULTI_STRING`, which was set when the schema was first created in the Monetate platform when the user selected **Comma Separated String** in step 4 of the [Create Dataset Schema wizard](https://docs.monetate.com/docs/create-a-product-catalog-dataset-schema). You can verify the data type on the **Attributes** tab of the mapped product catalog's details page in the Monetate platform.
In the example of the retailer wanting to boost products available at a customer's preferred location, the client must ensure that the data type for the `StoreStock` custom attribute is `MULTI_STRING` so that Personalized Search can parse the specific store ID values in the response and then filter and boost as the client defined in the request.
### Defining the Run-Time Boost or Bury Rule
Add the `boost` object to a site search query request to identify not only the attribute and its value(s) on which you want to base the boost or bury run-time rule but also how much you want the matching records boosted or buried in the results.
The `weight` key-value pair identifies the impact you want the rule to have on the matching records. The value must be a decimal between zero and 999. A value greater than 1 boosts the records within the rankings, and a value of zero to 1 buries the records within the rankings.
:::hint{type="warning"}
The `boost` object must appear before the other record-querying parameters in the request. Furthermore, you cannot use a negative number as the value of the `weight` key-value pair.
:::
:::CodeblockTabs
Example Site Search Query Request with Boosting
```json
{
"recordQueries": [
{
"boost": {
"filters": [
{
"key": "inStockStores",
"values": [
"190"
],
"weight": 900
}
]
},
"id": "productSearch",
"typeOfRequest": "SEARCH",
"settings": {
"query": {
"term": "shirt"
},
"limit": 20,
"typeOfRecords": [
"MONETATE_PRODUCT"
],
"fields": [
"id",
"name",
"inStock",
"inStockStores"
]
}
}
],
"suggestions": [],
"searchToken": "6.18.eJxdjrEOgjAURf"
}
```
:::
Keep in mind that including the `boost` object in a request doesn’t guarantee that product records that match its `filters` criteria are boosted to the very top or buried at the bottom of search results as indicated by the value of `weight` in all search queries.
## Returning Content Page Records
:::hint{type="info"}
To return records for product category merchandising pages and supplemental ecommerce content pages in site search results, you must first create the necessary [Content Pages datasets](https://docs.monetate.com/docs/content-pages-datasets) in the Monetate platform and associate each one with the mapped product catalog dataset.
:::
If you've uploaded one or more Content Pages datasets to Monetate and associated each one to the product catalog mapped for use in Personalized Search, then you can return in search results the records for supplemental ecommerce content published on your site—such as blog posts, buying guides, owner's manuals, specific category merchandising pages, and other media—alongside product records. Refer to the [Content Pages Datasets](https://docs.monetate.com/docs/content-pages-datasets) documentation in the Monetate Knowledge Base for the dataset specification and the steps for creating and updating a Content Pages dataset.
Any value that you pass in the `typeOfRecords` array for content records is derived from the value of the `category` attribute in each Content Pages dataset [associated with the mapped product catalog](https://docs.monetate.com/docs/edit-associated-product-catalogs). That value can be a standard value—`MONETATE_CMS` for any page that isn't a product detail page or product category page, and `MONETATE_CATEGORY` for a unique product category page—or a custom value used in the dataset. A custom value begins with an underscore character (`_`).
:::hint{type="warning"}
When using a custom `category` attribute value from a mapped Content Pages dataset in the `typeOfRecords` array, you must ensure that the letter case matches the letter case of the value as it appears in the dataset. For example, a retailer established `_video` as a custom value for its site's library of product demo videos. So that Personalized Search can examine those video records for matches for a customer's search query, the retailer passes `_video` in the `typeOfRecords` array in the Site Search request.
:::
Here's an example of a Personalized Site Search request configured to search records for unique category pages, along with its response:
:::CodeblockTabs
Example Site Search Query Request for Category Content Page Records
```json
{
"searchToken": "monetate-156925593843210765",
"recordQueries": [
{
"id": "CategorySearch",
"typeOfRequest": "SEARCH",
"settings": {
"typeOfSearch": "WILDCARD_AND",
"query": {
"term": "tops"
},
"limit": 5,
"typeOfRecords": [
"MONETATE_CATEGORY"
],
"fields": [
"id",
"name",
"description"
]
}
}
]
}
```
Response
```json
{
"queryResults": [
{
"id": "CategorySearch",
"meta": {
"qTime": 6,
"noOfResults": 5,
"totalResultsFound": 104,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "tops",
"searchToken": "monetate-156925593843210765",
"isPersonalised": false
},
"records": [
{
"name": "2026 Spring/Summer Tees Collection",
"id": "313",
"description": "Curated collection of t-shirts for spring/summer 2026"
"searchClickToken": "Monetate-NlIsC2LjE2NjIxE3DuMyNzE3MjExOyCd"
},
{
"name": "2025 Fall/Winter Crewnecks & Sweaters Collection",
"id": "316",
"description": "Curated collection of crewneck sweatshirts, long-sleeve t-shirts, and sweaters for fall/winter 2025 "
"searchClickToken": "Monetate-NlIsC254tg5t63t5g3DuMyNzE3MjExOyPe"
},
{
"name": "2026 Spring/Summer Button-Up Shirts Collection",
"id": "319",
"description": "Curated collection of button-up dress shirts for wearing with suits or more business casual looks"
"searchClickToken": "Monetate-Thg65y34deE2NjIxEuMyNzE3MjExOyCf"
},
{
... Additional records ...
}
]
}
]
}
```
:::
### Category Page Records and Personalized Category Page Queries
Be aware that a Site Search query request for category page records that you've uploaded to Monetate in a Content Pages dataset (`MONETATE_CATEGORY` is included in the `typeOfRecords` array) is not the same as a Personalized Category Page query request.
A Personalized Site Search request for `MONETATE_CATEGORY` content page records is a query that you make when you want to return category pages in response to a customer's search term anywhere on your site.
A Personalized Category Page request occurs *after* a customer arrives on a product category page. This request type searches for products based on products' category path(s). See [Personalized Category Page Queries](docId\:eAlnR9Q8Q_p8IWQ9rACcx) for more information and request examples.
### Returning Multiple Record Types
As previously noted, you can configure a Personalized Site Search request to identify complete records for both product records and records for one or more content page types. Here's an example of such a request along with its response:
:::CodeblockTabs
Example Site Search Query Request for Product and Content Page Records
```json
{
"searchToken": "monetate-180295149605129138",
"recordQueries": [
{
"id": "productSearch",
"typeOfRequest": "SEARCH",
"settings": {
"typeOfSearch": "WILDCARD_AND",
"query": {
"term": "battery lawn mowers"
},
"limit": 5,
"typeOfRecords": [
"MONETATE_PRODUCT"
],
"fields": [
"id",
"name",
"price",
"typeOfRecord"
]
}
},
{
"id": "contentSearchCMS",
"typeOfRequest": "SEARCH",
"settings": {
"typeOfSearch": "WILDCARD_AND",
"query": {
"term": "battery lawn mowers"
},
"limit": 3,
"typeOfRecords": [
"MONETATE_CMS"
],
"fields": [
"id",
"name",
"description",
"typeOfRecord"
]
}
},
{
"id": "contentSearchVideo",
"typeOfRequest": "SEARCH",
"settings": {
"typeOfSearch": "WILDCARD_AND",
"query": {
"term": "battery lawn mowers"
},
"limit": 3,
"typeOfRecords": [
"_video"
],
"fields": [
"id",
"name",
"description",
"typeOfRecord"
]
}
}
]
}
```
Response
```json
{
"queryResults": [
{
"id": "productSearch",
"meta": {
"qTime": 6,
"noOfResults": 5,
"totalResultsFound": 57,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "battery lawn mowers",
"searchToken": "monetate-180295149605129138",
"isPersonalised": false
},
"records": [
{
"id": "PL40VLM21D",
"name": "PowerLawn 40V 21-inch Battery-Powered Self-Propelled Lawn Mower",
"price": "499.99"
"typeOfRecord": "MONETATE_PRODUCT",
"searchClickToken": "Monetate-Z6HnY8PlQ2EcKqR3UaLiGaN7UwP1s"
},
{
"id": "RG56VLM20D",
"name": "Rolling Green 56V 18-inch Cordless Electric Self-Propelled Lawn Mower",
"price": "399.99"
"typeOfRecord": "MONETATE_PRODUCT",
"searchClickToken": "Monetate-C3JsY7PbQ9VeKdT7UzLaCiM4NbR0d"
},
{
"id": "PL40VLM20D",
"name": "PowerLawn 40V 20-inch Battery-Powered Self-Propelled Lawn Mower",
"price": "449.99"
"typeOfRecord": "MONETATE_PRODUCT",
"searchClickToken": "Monetate-R7FtU1SxD6CaLkY0IcPqAoN5MvE8s"
},
{
... Additional records ...
}
],
},
{
"id": "contentSearchCMS",
"meta": {
"qTime": 6,
"noOfResults": 3,
"totalResultsFound": 18,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "battery lawn mowers",
"searchToken": "monetate-180295149605129138",
"isPersonalised": false
},
"records": [
{
"id": "2026-BPLM-BG",
"name": "2026 Battery-Powered Lawn Mower Buyer's Guide",
"description": "Overview of key mowing features, explanation of terms related to battery power and mower performance, and a review of improvements and innovations available in battery-powered push lawn mowers for model year 2026"
"typeOfRecord": "MONETATE_CMS",
"searchClickToken": "Monetate-D4GfU3BmK6ZeOkW2NtXpLeH8RcS1b"
},
{
"id": "HT-SwampGas4Battery",
"name": "Power Up Your Lawn Care: How to Smartly Swap Gas-Powered Mowers, Trimmers, and More to Battery Power",
"description": "Guidance for selecting battery-powered lawn mowers, string trimmers, edgers, and other lawn care equipment, with a comparison of run time, repair costs, lifespans of battery-powered tools and gas-powered tools"
"typeOfRecord": "MONETATE_CMS",
"searchClickToken": "Monetate-GaX8CmE5QlDW3lnOrB4j2oW4qMTv1"
},
{
"id": "101-LM",
"name": "Lawn Mowers 101",
"description": "Introduction to the types of lawn mowers available for sale, covering manual reel mowers, gas-powered mowers and mulchers, battery-powered mowers, riding lawn mowers, and lawn tractors. Explanation of various design features such as side catchers, rear catchers, mulching attachments, horsepower, brushless engines, and more."
"typeOfRecord": "MONETATE_CMS",
"searchClickToken": "Monetate-R7FtU1SxD6CaLkY0IcPqAoN5MvE8s"
},
{
"id": "contentSearchVideo",
"meta": {
"qTime": 6,
"noOfResults": 3,
"totalResultsFound": 9,
"typeOfSearch": "WILDCARD_AND",
"offset": 0,
"debuggingInformation": {},
"notificationCode": 1,
"searchedTerm": "battery lawn mowers",
"searchToken": "monetate-180295149605129138",
"isPersonalised": false
},
"records": [
{
"id": "LCT-2026-BPLM-T10",
"name": "Tested: 2026's Top Battery-Powered Lawn Mowers",
"description": "The Lawn Care Team tests the top 10 battery-powered push lawn mowers on a variety of grasses and turfs in a variety of environments to find out which models from the best-selling brands—including PowerLawn, Rolling Green, Jandi, and more—are worth the investment"
"typeOfRecord": "_video",
"searchClickToken": "Monetate-6nPhOc1T3L8d4HwXelg2Z5M7hK0Tl"
},
{
"id": "LCT-Motors",
"name": "Brush Up on Brushless and Brushed Battery-Powered Lawn Equipment",
"description": "The Lawn Care Team demonstrates the differences between brushless and brushed motors used in battery-powered lawn mowers, string trimmers, and other lawn care tools"
"typeOfRecord": "_video",
"searchClickToken": "Monetate-8wTlKdyJaQ7zU9dEUmGqFUeYYQ4uZ"
},
{
"id": "LCT-BPLM-Options",
"name": "Mow Power: Choosing the Right Battery-Powered Lawn Mower for Your Yard",
"description": "The Lawn Care Team breaks down how to determine the deck width, battery amp hours, battery voltage, and other options available for battery-powered lawn mowers can best meet your lawn care needs"
"typeOfRecord": "_video",
"searchClickToken": "Monetate-J8m3gEiNP2Vc0Bj7uPzKuUw2B7b2t"
}
]
}
]
}
```
:::
Monetate recommends passing only one record type value in each `typeOfRecords` occurence in a request as shown in the example instead of combining all the record type values into one `typeOfRecords` array. If you pass multiple record type values in a single `typeOfRecords` occurence, then Personalized Search returns all the results records without any defined order, which can make it harder for you to format.