:::warning \*Note To improve platform service stability, the platform will set an upper limit on the number of recommended items returned, starting from **March 3, 2026**. * The upper limit for `page_size` will be **400**. * If the page_size parameter is greater than 400, the API will return an `InvalidParameter` error. * If you need a temporary exemption, contact Volcano Engine after\-sales service to apply for the allowlist. * To experience more of Viking AI's search capabilities, visit [Viking AI Search Engine, an all-in-one intelligent engine for enterprise search, recommendation, and Q&A](https://www.volcengine.com/product/AI-Search-Rec). ::: # Notes * **Usage Limits:** * Due to HTTP body size limits, the maximum body size for a single request cannot exceed 10 MB. # Request Description * Request Method: POST * Request URL: * North China: https://aisearch.cn\-beijing.volces.com/api/v1/application/`{application_id}`/`{scene_id}` * Johor: https://aisearch.ap\-southeast\-1.volces.com/api/v1/application/`{application_id}`/`{scene_id}` `{application_id}`: The unique identifier for an application, assigned by the system after creation. It can be viewed in the console. `{scene_id}`: The unique identifier for a recommendation scene, assigned by the system after creation. The format is scene{id} (e.g., sceneR01asDfs). You can copy the Scene ID by hovering over the scene name under 'Recommendation Experience' in the console. **The Scene ID starts with ** **`scene`** **.**

![图片](https://p9-arcosite.byteimg.com/obj/tos-cn-i-goo7wpa0wc/48aac254905749369c1a17e4027ac13e =2890x) ## Authentication Method You can authenticate with an API Key or an Access Key. For details, see the [API Authentication documentation.](https://www.volcengine.com/docs/85296/1544950) # Request Parameters ## Request Body |**Parameter** |**Data Type** |**Required** |**Example Value** |**Description** | |---|---|---|---|---| |user |**User**|%%require%% |See: [User](/docs/85296/1788543#3032d22a) |**User Information**|\ | | | | |Specifies the user who triggered this API call. | |parent_items |Array<**Item**\> |**`Conditionally required`** |See: [Item](/docs/85296/1788543#47d0575d) |**Item on the details page (parent item)** |\ | | | | |In the "Recommended on details page" scenario, the unique ID of the item on the current details page must be provided. The item ID must exist in the item dataset. | |page_size |Integer |**`Optional`** |10 |**Configure maximum returned quantity**|\ | | | | |If not provided, the return quantity configured in the console for the current scene is used. Pagination is not supported. The results are returned in a single batch.|\ | | | | |:::tip \*Does the returned quantity not match the configured quantity?|\ | | | | |The returned count is not necessarily equal to the `page_size` parameter. If, after deduplication and filtering, the number of recommendable items is less than `page_size`, the returned count may be less than the configured count.|\ | | | | ||\ | | | | |:::| |disable_personalize|Boolean |**`Optional`** |`true` |**Disable personalized recommendations**|\ |%%add%% | | | |For compliance, the default is `false (enables personalized recommendations)`.|\ | | | | |When personalized recommendations are disabled, recommendations will only be based on non\-personalized recalls, such as trending items and parent item similarity recalls. Recommended items will still adhere to your business configuration rules, including boosting, demotion, filtering, deduplication, and diversity rules.|\ | | | | |:::tip \*Description|\ | | | | |Disabling personalized recommendations increases the probability of receiving empty results.|\ | | | | ||\ | | | | |:::| |session_id |String |**`Optional`** |`"session_123"` |**A unique identifier for a user session.** |\ | | | | |Use a custom and unique value for each session, such as a UUID.|\ | | | | |> Learn more: [Pinned Recommended Items](/docs/85296/1863361)|\ | | | | ||\ | | | | |When pinned items are configured for a recommendation scene and 'Repeat recommendations on each refresh' is disabled, the platform uses the `session_id` to check if the pinned configuration has been applied to a visit within **24 hours**.|\ | | | | ||\ | | | | |* If this parameter is not provided, repeated pinning will occur for the **same visit within 24 hours**. | |filter |Object<**Filter**\> |**`Optional`** |See: [Filter](/docs/85296/1788543#db3f2d55) |**Dynamic filter parameter**|\ | | | | |If 'Dynamic Parameter Filtering' is configured for the scene's recommendation scope, you must pass the parameter values through this field. The platform automatically uses the value to populate the parameter's filter conditions. The platform automatically ignores missing dynamic filter conditions. | |output_fields |Array |**`Optional`** |`["title", "category"]`|**Return Fields**|\ | | | | |The fields returned by the recommended items API. All fields are returned by default. For nested object fields (Object, Array), only passing the top\-level field name is supported.|\ | | | | ||\ | | | | |* Incorrect field names and fields nested within an Object are automatically ignored.|\ | | | | ||\ | | | | |:::tip \*Why aren't all fields returned?|\ | | | | |When an item has many fields, returning all of them increases the response speed of the recommendation API. Return only necessary fields to reduce latency, improve API response performance, and enhance log readability.|\ | | | | ||\ | | | | |:::| |context |Object<**Context**\> |**`Optional`** |See: [Context](/docs/85296/1788543#65900099) |**Request context**|\ | | | | |Affects the recall processing logic for recommended items and the returned item results. | |conditional_boost |Array<**Conds**\> |**`Optional`** |See: [Conds](/docs/85296/2123292#ca81d523) |**API\-Level Promotion and Demotion Configuration**|\ | | | | |> To learn more, see: [Recommendation API uplift and demotion rule configuration](/docs/85296/2123292)|\ | | | | ||\ | | | | |The platform automatically merges and applies the promotion and demotion rules configured in both the console and the API. If omitted, only the promotion and demotion rules configured in the console will apply. | ## Data Structure ### User |**Parameter** |**Data Type** |**Required** |**Example Value** |**Description** | |---|---|---|---|---| |_user_id |String |%%require%% |`"user_199432"` |**A unique identifier for the user.** |\ | | | | |Identifies the user who triggered the API call. For users who are not logged in, you can use a globally unique identifier, such as a device ID, as a virtual user ID. | ### Item |**Parameter** |**Data Type** |**Required** |**Example Value** |**Description** | |---|---|---|---|---| |_id |String |**`Conditionally required`** |`"item_1001"` |**The unique ID of the item.** |\ | | | | |In "Recommended on Detail Page" scenarios, you must provide the unique ID of the item on the current detail page. The item ID must exist in the item dataset. | ### Filter |**Parameter** |**Example value** |**Description** | |---|---|---| |Parameter name |```JSON|**Dynamic filter parameters**|\ | |{|> Depends on the platform configuration. See: [Dynamic recommendation scope configuration](/docs/85296/1863360)|\ | | "category": ["shoes"],||\ | | "max_price": 100.50|Used to pass dynamic filtering condition parameters that are consistent with the platform configuration. The parameter names must align with the platform configuration. **The platform automatically ignores missing dynamic filtering conditions.** |\ | |}|:::warning \*Note|\ | |```|The data type of the parameter value must be the same as the item field. Rules with misaligned data formats are invalid and will be automatically ignored.|\ | | ||\ | | |:::| ### Context |**Parameter** |**Example value** |**Description** | |---|---|---| |location |```JSON|**Request user location**|\ | |{|> This depends on the platform configuration. See [User geographic location-based ranking boost and demotion](/docs/85296/1963520).|\ | | "latitude": "12.1243",||\ | | "longitude": "-012.1223"|Supports passing the user's location to configure geolocation\-based item boosting and demotion. The input data must be a string. **If the input is invalid, the platform automatically ignores the configuration.** |\ | |}| |\ | |```| |\ | | | | --- # Response parameters ## Request response |**Parameter** |**Type** |**Example value** |**Description** | |---|---|---|---| |request_id |String |`"25ee998a-5462-9385-9f18-035f1da7a6e5"` |**Request ID**|\ | | | |The unique identifier for a request, which helps you to locate it quickly. | |result |Object |Contains the content of the `rec_results` and `extra_info` parameters. |**Complete content response** | |rec_results |Array<**RecommendResults**\> |See: [RecommendResults](/docs/85296/1788543#48767e7f) |**A list of recommended items, including their unique identifiers and detailed information.** | |extra_info |Object<**ExtraInfo**\> |See: [ExtraInfo](/docs/85296/1788543#09fcad10) |**Additional information about request processing**|\ | | | |Use this to check the recommendation request processing logic, which helps you understand and troubleshoot the validity of your configuration and whether the processing logic meets business requirements. | ## Data structure ### RecommendResults |**Parameter** |**Type** |**Sample value** |**Description** | |---|---|---|---| |_id |String |"item_1003" |**Unique item key**|\ | | | |Item ID of the recommended item. | |display_fields |Object |```JSON|**Item data content object**|\ | | |{|The returned fields can be defined by the `output_fields` request parameter. By default, all fields are returned, and their content is consistent with the imported item dataset.|\ | | | "item_count": 1234,| |\ | | | "update_time": 1752238693295,| |\ | | | "item_id": "item_1003"| |\ | | |}| |\ | | |```| |\ | | | | | ### ExtraInfo |**Parameter** |**Type** |**Example Value** |**Description** | |---|---|---|---| |forced_item_info |Object <**ForcedItems**\> |See below: [ForcedItems](/docs/85296/1788543#30f2849c) |**Pinned Item Processing Logic**|\ | | | |When the pinned item configuration is enabled for a recommendation scene, the parameter returns the pinned item ID and effective status, allowing you to check if it works as expected. | |omitted_params |Array |`["category", "max_price"]` |**Automatically Ignored Dynamic Filtering Conditions**|\ | | | |The platform automatically ignores invalid or empty dynamic filtering conditions to ensure the recommendation API returns results. This parameter lists the names of ignored [Filter](/docs/85296/1788543#db3f2d55)parameters in the request. | |boost_status |Array |`["success", "field not found", "invalid operator"]` |**API Promotion and Demotion Rule Status**|\ | | | |> To understand the meaning of each status, see: [Status](/docs/85296/2123292#49cb8580)|\ | | | ||\ | | | |Returns the execution status of API rules when promotion and demotion rules are passed in a request.|\ | | | |:::tip \*Return Order Logic|\ | | | |**Strictly follow ** [Conds](/docs/85296/2123292#ca81d523) ** ** **the parameter ** [BoostConfig](/docs/85296/2123292#38cf87d9) ** ** **order.** |\ | | | |For example: If the first [BoostConfig](/docs/85296/2123292#38cf87d9) configuration runs successfully,`boost_status`'s first status will be `success`.|\ | | | ||\ | | | |:::| ### ForcedItems |**Parameter** |**Type** |**Example Value** |**Description** | |---|---|---|---| |item_ids |Array |`["60493", "52937"]` |**Successfully pinned item IDs**|\ | | | |If an item ID is not in the item dataset, the platform automatically removes the item. | |skipped |Boolean |`false` |**Pin status**|\ | | | |> For session_id parameter configuration, see: [Request Body](/docs/85296/1788543#4fa39169)|\ | | | ||\ | | | ||\ | | | |* `true`: The `session_id` has appeared within the last 24 hours, and the pin is inactive|\ | | | |* `false`: The `session_id` has not appeared within the last 24 hours, and the pin is active. | --- # API Example ## Request Example ```mixin-react return ( ### Home Page Recommendation \`\`\`Bash curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/application/\\${application_id}/\\${scene_id}' \\ -H 'Content-Type: application/json' \\ -H 'Authorization: Bearer ' \\ -d '{ "user": { "_user_id": "user_199432" }, "page_size": 10, "session_id": "GrrZCRhl", "filter": { "category": "shoes", "max_price": 100.5 }, "output_fields": ["item_count", "update_time","item_id"], "context": { "location": { "latitude": "+12.12", "longitude": "+012.12" } }, "conditional_boost": [{ "conds": [ { "field": "brand", "op": "must", "conds": ["apple","samsung","huawei"] } ], "boost": 0.8 }] }' \`\`\` `}> ### Details Page Recommendation \`\`\`Bash curl -X POST 'https://aisearch.cn-beijing.volces.com/api/v1/application/\\${application_id}/\\${scene_id}' \\ -H 'Content-Type: application/json' \\ -H 'Authorization: Bearer ' \\ -d '{ "user": { "_user_id": "user_199432" }, "parent_items": [{ "_id": "item_id_1002" }], "page_size": 10, "session_id": "GrrZCRhl", "filter": { "category": "shoes", "max_price": 100.5 }, "output_fields": ["item_count", "update_time","item_id"], "context": { "location": { "latitude": "+12.12", "longitude": "+012.12" } }, "conditional_boost": [{ "conds": [ { "field": "brand", "op": "must", "conds": ["apple","samsung","huawei"] } ], "boost": 0.8 }] }' \`\`\` ## `}>); ``` ## Response Example ```JSON { "request_id": "25ee998a-5462-9385-9f18-035f1da7a6e5", "results": { "rec_results": [ { "_id": "688932914577129760", "display_fields": { "item_count": 1234, "update_time": 1752238692193, "item_id": "item_1004" } }, { "_id": "528424731470549718", "display_fields": { "item_count": 1234, "update_time": 1752238693295, "item_id": "item_1003" } } ], "extra_info": { "forced_item_info": { "item_ids": ["60493","52937"], "skipped": false }, "omitted_params": ["max_price"], "boost_status":["success"] } } } ``` # Error Handling ## Error Code For this API's error codes, refer to [Common Error Codes](/docs/85296/1544941)the documentation. :::warning \*Note To enhance platform service stability, we will introduce a universal limit on the number of returned recommended items starting **March 3, 2026**. * The upper limit for the number of returned items, `page_size`, will be **400**. * If the page_size parameter is greater than 400, the API will return an `InvalidParameter` error. * For a temporary exemption, contact Volcengine After\-sales Service to apply for the allowlist. * To explore more of Viking AI's search capabilities, visit: [Viking AI Search Engine, an integrated intelligent engine for enterprise search, recommendation, and question answering](https://www.volcengine.com/product/AI-Search-Rec). :::