# User-Item Interactions > Source: https://docs.recombee.com/api/interactions > For the complete documentation index, see [llms.txt](/llms.txt). # User-Item Interactions The following methods allow adding, deleting, and listing interactions between the users and the items. ## Detail Views post ### Add Detail View Allowed on Client-Side Adds a detail view of the given item made by the given user. ```js client.send(new recombee.AddDetailView(userId, itemId, { // optional parameters: timestamp: '2022-05-13T18:25:43Z', // string / number duration: 35, // integer cascadeCreate: true, // boolean recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837', // string additionalData: {}, // Object autoPresented: false, // boolean })); ``` --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **body** Required: **Yes** User who viewed the item --- itemId String Located in: **body** Required: **Yes** Viewed item --- timestamp String Number Located in: **body** Required: **No** UTC timestamp of the view as ISO8601-1 pattern or UTC epoch time. The default value is the current time. --- duration Integer Located in: **body** Required: **No** Duration of the view --- cascadeCreate Boolean Located in: **body** Required: **No** Sets whether the given user/item should be created if not present in the database. --- recommId String Located in: **body** Required: **No** Since version: **2.2.0** If this detail view is based on a recommendation request, `recommId` is the id of the clicked recommendation. --- additionalData Object Located in: **body** Required: **No** Since version: **2.3.0** Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable. --- autoPresented Boolean Located in: **body** Required: **No** Since version: **6.0.0** Indicates whether the item was automatically presented to the user (e.g., in a swiping feed) or explicitly requested by the user (e.g., by clicking on a link). Defaults to `false`. --- #### Responses 200 Successful operation. --- 400 Given `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. `timestamp` or `duration` is not a real number ≥ 0. --- 404 The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- 409 A detail view of the exact same `userId`, `itemId`, and `timestamp` is already present in the database. Note that a user may view an item's details multiple times, yet triplets (`userId`, `itemId`, `timestamp`) must be unique. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database. --- delete ### Delete Detail View Deletes an existing detail view uniquely specified by (`userId`, `itemId`, and `timestamp`) or all the detail views with the given `userId` and `itemId` if `timestamp` is omitted. ```js client.send(new requests.DeleteDetailView(userId, itemId, { // optional parameters: timestamp: 1652466343, // number })); ``` --- Calls Limit Per Minute 1000 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **query** Required: **Yes** ID of the user who made the detail view. --- itemId String Located in: **query** Required: **Yes** ID of the item whose details were viewed. --- timestamp Number Located in: **query** Required: **No** Unix timestamp of the detail view. If the `timestamp` is omitted, then all the detail views with the given `userId` and `itemId` are deleted. --- #### Responses 200 Successful operation. --- 400 Given `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or `timestamp` is not a real number ≥ 0. --- 404 The `userId`, `itemId`, or detail view with the given (`userId`, `itemId`, `timestamp`) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- get ### List Item Detail Views Lists all the detail views of the given item ever made by different users. ```js const result = await client.send(new requests.ListItemDetailViews(itemId)); ``` --- Calls Limit Per Minute 60 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- itemId String Located in: **path** Required: **Yes** ID of the item whose detail views are to be listed. --- #### Responses 200 Successful operation. ``` [ { "itemId": "item-x", "userId": "user-a", "duration": 14.23, "autoPresented": true, "timestamp": 1348151906.0 }, { "itemId": "item-x", "userId": "user-b", "duration": null, "autoPresented": false, "timestamp": 1348239363.0 } ] ``` --- 400 The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. --- 404 Given `itemId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- get ### List User Detail Views Lists all the detail views of different items ever made by the given user. ```js const result = await client.send(new requests.ListUserDetailViews(userId)); ``` --- Calls Limit Per Minute 60 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **path** Required: **Yes** ID of the user whose detail views are to be listed. --- #### Responses 200 Successful operation. ``` [ { "itemId": "item-y", "userId": "user-a", "duration": 134.03, "autoPresented": true, "timestamp": 1348139180.0 }, { "itemId": "item-x", "userId": "user-a", "duration": 14.23, "autoPresented": false, "timestamp": 1348151906.0 } ] ``` --- 400 The `userId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. --- 404 Given `userId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- ## Purchases post ### Add Purchase Allowed on Client-Side Adds a purchase of the given item made by the given user. ```js client.send(new recombee.AddPurchase(userId, itemId, { // optional parameters: timestamp: '2022-05-13T18:25:43Z', // string / number cascadeCreate: true, // boolean amount: 1, // number price: 25.0, // number profit: 5.0, // number recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837', // string additionalData: {}, // Object })); ``` --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **body** Required: **Yes** User who purchased the item --- itemId String Located in: **body** Required: **Yes** Purchased item --- timestamp String Number Located in: **body** Required: **No** UTC timestamp of the purchase as ISO8601-1 pattern or UTC epoch time. The default value is the current time. --- cascadeCreate Boolean Located in: **body** Required: **No** Sets whether the given user/item should be created if not present in the database. --- amount Number Located in: **body** Required: **No** Since version: **1.6.0** Amount (number) of purchased items. The default is 1\. For example, if `user-x` purchases two `item-y` during a single order (session...), the `amount` should equal 2. --- price Number Located in: **body** Required: **No** Since version: **1.6.0** Price paid by the user for the item. If `amount` is greater than 1, the sum of prices of all the items should be given. --- profit Number Located in: **body** Required: **No** Since version: **1.6.0** Your profit from the purchased item. The profit is natural in the e-commerce domain (for example, if `user-x` purchases `item-y` for $100 and the gross margin is 30 %, then the profit is $30) but is also applicable in other domains (for example, at a news company it may be income from a displayed advertisement on article page). If `amount` is greater than 1, the sum of profit of all the items should be given. --- recommId String Located in: **body** Required: **No** Since version: **2.2.0** If this purchase is based on a recommendation request, `recommId` is the id of the clicked recommendation. --- additionalData Object Located in: **body** Required: **No** Since version: **2.3.0** Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable. --- #### Responses 200 Successful operation. --- 400 The `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. `timestamp` is not a real number ≥ 0. --- 404 The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- 409 A purchase of the exact same `userId`, `itemId`, and `timestamp` is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database. --- delete ### Delete Purchase Deletes an existing purchase uniquely specified by `userId`, `itemId`, and `timestamp` or all the purchases with the given `userId` and `itemId` if `timestamp` is omitted. ```js client.send(new requests.DeletePurchase(userId, itemId, { // optional parameters: timestamp: 1652466343, // number })); ``` --- Calls Limit Per Minute 1000 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **query** Required: **Yes** ID of the user who made the purchase. --- itemId String Located in: **query** Required: **Yes** ID of the item which was purchased. --- timestamp Number Located in: **query** Required: **No** Unix timestamp of the purchase. If the `timestamp` is omitted, then all the purchases with the given `userId` and `itemId` are deleted. --- #### Responses 200 Successful operation. --- 400 Given `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or `timestamp` is not a real number ≥ 0. --- 404 The `userId`, `itemId`, or purchase with the given (`userId`, `itemId`, `timestamp`) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- get ### List Item Purchases Lists all the ever-made purchases of the given item. ```js const result = await client.send(new requests.ListItemPurchases(itemId)); ``` --- Calls Limit Per Minute 60 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- itemId String Located in: **path** Required: **Yes** ID of the item whose purchases are to be listed. --- #### Responses 200 Successful operation. ``` [ { "itemId": "item-x", "userId": "user-a", "timestamp": 1348151906.0 }, { "itemId": "item-x", "userId": "user-b", "timestamp": 1348327154.0 } ] ``` --- 400 The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. --- 404 Given `itemId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- get ### List User Purchases Lists all the purchases ever made by the given user. ```js const result = await client.send(new requests.ListUserPurchases(userId)); ``` --- Calls Limit Per Minute 60 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **path** Required: **Yes** ID of the user whose purchases are to be listed. --- #### Responses 200 Successful operation. ``` [ { "itemId": "item-x", "timestamp": 1348151906.0, "userId": "user-a" }, { "itemId": "item-z", "timestamp": 1348239363.0, "userId": "user-a" } ] ``` --- 400 The `userId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. --- 404 Given `userId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- ## Ratings post ### Add Rating Allowed on Client-Side Adds a rating of the given item made by the given user. ```js client.send(new recombee.AddRating(userId, itemId, rating, { // optional parameters: timestamp: '2022-05-13T18:25:43Z', // string / number cascadeCreate: true, // boolean recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837', // string additionalData: {}, // Object })); ``` --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **body** Required: **Yes** User who submitted the rating --- itemId String Located in: **body** Required: **Yes** Rated item --- timestamp String Number Located in: **body** Required: **No** UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time. --- rating Number Located in: **body** Required: **Yes** Rating rescaled to interval \[-1.0,1.0\], where -1.0 means the worst rating possible, 0.0 means neutral, and 1.0 means absolutely positive rating. For example, in the case of 5-star evaluations, rating = (numStars-3)/2 formula may be used for the conversion. --- cascadeCreate Boolean Located in: **body** Required: **No** Sets whether the given user/item should be created if not present in the database. --- recommId String Located in: **body** Required: **No** Since version: **2.2.0** If this rating is based on a recommendation request, `recommId` is the id of the clicked recommendation. --- additionalData Object Located in: **body** Required: **No** Since version: **2.3.0** Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable. --- #### Responses 200 Successful operation. --- 400 The `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or rating is not a real number from \[-1.0,1.0\], or timestamp is not a real number ≥ 0. --- 404 The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- 409 A rating of the exact same `userId`, `itemId`, and `timestamp` is already present in the database. Note that a user may rate an item multiple times, yet triplets (userId, itemId, timestamp) must be unique. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database. --- delete ### Delete Rating Deletes an existing rating specified by (`userId`, `itemId`, `timestamp`) from the database or all the ratings with the given `userId` and `itemId` if `timestamp` is omitted. ```js client.send(new requests.DeleteRating(userId, itemId, { // optional parameters: timestamp: 1652466343, // number })); ``` --- Calls Limit Per Minute 1000 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **query** Required: **Yes** ID of the user who rated the item. --- itemId String Located in: **query** Required: **Yes** ID of the item which was rated. --- timestamp Number Located in: **query** Required: **No** Unix timestamp of the rating. If the `timestamp` is omitted, then all the ratings with the given `userId` and `itemId` are deleted. --- #### Responses 200 Successful operation. --- 400 Given `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or `timestamp` is not a real number ≥ 0. --- 404 The `userId`, `itemId` or rating with the given (`userId`, `itemId`, `timestamp`) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- get ### List Item Ratings Lists all the ratings of an item ever submitted by different users. ```js const result = await client.send(new requests.ListItemRatings(itemId)); ``` --- Calls Limit Per Minute 60 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- itemId String Located in: **path** Required: **Yes** ID of the item whose ratings are to be listed. --- #### Responses 200 Successful operation. ``` [ { "itemId": "item-x", "userId": "user-a", "rating": -0.25, "timestamp": 1348151906.0 }, { "itemId": "item-x", "userId": "user-b", "rating": 0.0, "timestamp": 1348239363.0 } ] ``` --- 400 The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. --- 404 Given `itemId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- get ### List User Ratings Lists all the ratings ever submitted by the given user. ```js const result = await client.send(new requests.ListUserRatings(userId)); ``` --- Calls Limit Per Minute 60 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **path** Required: **Yes** ID of the user whose ratings are to be listed. --- #### Responses 200 Successful operation. ``` [ { "itemId": "item-y", "userId": "user-a", "rating": 0.5, "timestamp": 1348139180.0 }, { "itemId": "item-x", "userId": "user-a", "rating": -0.25, "timestamp": 1348151906.0 } ] ``` --- 400 The `userId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. --- 404 Given `userId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- ## Cart Additions post ### Add Cart Addition Allowed on Client-Side Adds a cart addition of the given item made by the given user. ```js client.send(new recombee.AddCartAddition(userId, itemId, { // optional parameters: timestamp: '2022-05-13T18:25:43Z', // string / number cascadeCreate: true, // boolean amount: 1, // number price: 25.0, // number recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837', // string additionalData: {}, // Object })); ``` --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **body** Required: **Yes** User who added the item to the cart --- itemId String Located in: **body** Required: **Yes** Item added to the cart --- timestamp String Number Located in: **body** Required: **No** UTC timestamp of the cart addition as ISO8601-1 pattern or UTC epoch time. The default value is the current time. --- cascadeCreate Boolean Located in: **body** Required: **No** Sets whether the given user/item should be created if not present in the database. --- amount Number Located in: **body** Required: **No** Since version: **1.6.0** Amount (number) added to cart. The default is 1\. For example, if `user-x` adds two `item-y` during a single order (session...), the `amount` should equal 2. --- price Number Located in: **body** Required: **No** Since version: **1.6.0** Price of the added item. If `amount` is greater than 1, the sum of prices of all the items should be given. --- recommId String Located in: **body** Required: **No** Since version: **2.2.0** If this cart addition is based on a recommendation request, `recommId` is the id of the clicked recommendation. --- additionalData Object Located in: **body** Required: **No** Since version: **2.3.0** Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable. --- #### Responses 200 Successful operation. --- 400 The `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, `timestamp` is not a real number ≥ 0. --- 404 The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- 409 A cart addition of the exact same `userId`, `itemId`, and `timestamp` is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database. --- delete ### Delete Cart Addition Deletes an existing cart addition uniquely specified by `userId`, `itemId`, and `timestamp` or all the cart additions with the given `userId` and `itemId` if `timestamp` is omitted. ```js client.send(new requests.DeleteCartAddition(userId, itemId, { // optional parameters: timestamp: 1652466343, // number })); ``` --- Calls Limit Per Minute 1000 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **query** Required: **Yes** ID of the user who made the cart addition. --- itemId String Located in: **query** Required: **Yes** ID of the item which was added to the cart. --- timestamp Number Located in: **query** Required: **No** Unix timestamp of the cart addition. If the `timestamp` is omitted, then all the cart additions with the given `userId` and `itemId` are deleted. --- #### Responses 200 Successful operation. --- 400 Given `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or `timestamp` is not a real number ≥ 0. --- 404 The `userId`, `itemId`, or cart addition with the given (`userId`, `itemId`, `timestamp`) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- get ### List Item Cart Additions Lists all the ever-made cart additions of the given item. ```js const result = await client.send(new requests.ListItemCartAdditions(itemId)); ``` --- Calls Limit Per Minute 60 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- itemId String Located in: **path** Required: **Yes** ID of the item whose cart additions are to be listed. --- #### Responses 200 Successful operation. ``` [ { "itemId": "item-x", "userId": "user-a", "timestamp": 1348151906.0 }, { "itemId": "item-x", "userId": "user-a", "timestamp": 1348327154.0 } ] ``` --- 400 The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. --- 404 Given `itemId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- get ### List User Cart Additions Lists all the cart additions ever made by the given user. ```js const result = await client.send(new requests.ListUserCartAdditions(userId)); ``` --- Calls Limit Per Minute 60 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **path** Required: **Yes** ID of the user whose cart additions are to be listed. --- #### Responses 200 Successful operation. ``` [ { "itemId": "item-x", "timestamp": 1348151906.0, "userId": "user-a" }, { "itemId": "item-z", "timestamp": 1348239363.0, "userId": "user-a" } ] ``` --- 400 The `userId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. --- 404 Given `userId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- ## Bookmarks post ### Add Bookmark Allowed on Client-Side Adds a bookmark of the given item made by the given user. ```js client.send(new recombee.AddBookmark(userId, itemId, { // optional parameters: timestamp: '2022-05-13T18:25:43Z', // string / number cascadeCreate: true, // boolean recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837', // string additionalData: {}, // Object })); ``` --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **body** Required: **Yes** User who bookmarked the item --- itemId String Located in: **body** Required: **Yes** Bookmarked item --- timestamp String Number Located in: **body** Required: **No** UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time. --- cascadeCreate Boolean Located in: **body** Required: **No** Sets whether the given user/item should be created if not present in the database. --- recommId String Located in: **body** Required: **No** Since version: **2.2.0** If this bookmark is based on a recommendation request, `recommId` is the id of the clicked recommendation. --- additionalData Object Located in: **body** Required: **No** Since version: **2.3.0** Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable. --- #### Responses 200 Successful operation. --- 400 The `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, `timestamp` is not a real number ≥ 0. --- 404 The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- 409 A bookmark of the exact same `userId`, `itemId`, and `timestamp` is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database. --- delete ### Delete Bookmark Deletes a bookmark uniquely specified by `userId`, `itemId`, and `timestamp` or all the bookmarks with the given `userId` and `itemId` if `timestamp` is omitted. ```js client.send(new requests.DeleteBookmark(userId, itemId, { // optional parameters: timestamp: 1652466343, // number })); ``` --- Calls Limit Per Minute 1000 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **query** Required: **Yes** ID of the user who made the bookmark. --- itemId String Located in: **query** Required: **Yes** ID of the item which was bookmarked. --- timestamp Number Located in: **query** Required: **No** Unix timestamp of the bookmark. If the `timestamp` is omitted, then all the bookmarks with the given `userId` and `itemId` are deleted. --- #### Responses 200 Successful operation. --- 400 Given `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or `timestamp` is not a real number ≥ 0. --- 404 The `userId`, `itemId`, or bookmark with the given (`userId`, `itemId`, `timestamp`) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- get ### List Item Bookmarks Lists all the ever-made bookmarks of the given item. ```js const result = await client.send(new requests.ListItemBookmarks(itemId)); ``` --- Calls Limit Per Minute 60 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- itemId String Located in: **path** Required: **Yes** ID of the item whose bookmarks are to be listed. --- #### Responses 200 Successful operation. ``` [ { "itemId": "item-x", "userId": "user-a", "timestamp": 1348151906.0 }, { "itemId": "item-x", "userId": "user-a", "timestamp": 1348327154.0 } ] ``` --- 400 The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. --- 404 Given `itemId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- get ### List User Bookmarks Lists all the bookmarks ever made by the given user. ```js const result = await client.send(new requests.ListUserBookmarks(userId)); ``` --- Calls Limit Per Minute 60 --- #### Parameters databaseId String Located in: **path** Required: **Yes** ID of your database. --- userId String Located in: **path** Required: **Yes** ID of the user whose bookmarks are to be listed. --- #### Responses 200 Successful operation. ``` [ { "itemId": "item-x", "timestamp": 1348151906.0, "userId": "user-a" }, { "itemId": "item-z", "timestamp": 1348239363.0, "userId": "user-a" } ] ``` --- 400 The `userId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. --- 404 Given `userId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- ## View Portions post ### Set View Portion Allowed on Client-Side Sets viewed portion of an item (for example a video or article) by a user (at a session). If you send a new request with the same (`userId`, `itemId`, `sessionId`), the portion gets updated. ```js client.send(new recombee.SetViewPortion(userId, itemId, portion, { // optional parameters: sessionId: 'ABAD1D', // string timestamp: '2022-05-13T18:25:43Z', // string / number cascadeCreate: true, // boolean recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837', // string additionalData: {}, // Object autoPresented: false, // boolean timeSpent: 42, // number })); ``` --- Since version 2.1.0 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **2.1.0** ID of your database. --- userId String Located in: **body** Required: **Yes** Since version: **2.1.0** User who viewed a portion of the item --- itemId String Located in: **body** Required: **Yes** Since version: **2.1.0** Viewed item --- portion Number Located in: **body** Required: **Yes** Since version: **2.1.0** Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the actual viewed part of the item, no matter the seeking. For example, if the user seeked immediately to half of the item and then viewed 10% of the item, the `portion` should still be `0.1`. --- sessionId String Located in: **body** Required: **No** Since version: **2.1.0** ID of the session in which the user viewed the item. Default is `null` (`None`, `nil`, `NULL` etc., depending on the language). --- timestamp String Number Located in: **body** Required: **No** Since version: **2.1.0** UTC timestamp of the view portion as ISO8601-1 pattern or UTC epoch time. The default value is the current time. --- cascadeCreate Boolean Located in: **body** Required: **No** Since version: **2.1.0** Sets whether the given user/item should be created if not present in the database. --- recommId String Located in: **body** Required: **No** Since version: **2.2.0** If this view portion is based on a recommendation request, `recommId` is the id of the clicked recommendation. --- additionalData Object Located in: **body** Required: **No** Since version: **2.3.0** Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable. --- autoPresented Boolean Located in: **body** Required: **No** Since version: **6.0.0** Indicates whether the item was automatically presented to the user (e.g., in a swiping feed) or explicitly requested by the user (e.g., by clicking on a link). Defaults to `false`. --- timeSpent Number Located in: **body** Required: **No** Since version: **6.0.0** The duration (in seconds) that the user viewed the item. In update requests, this value may only increase and is required only if it has changed. --- #### Responses 200 Successful operation. --- 400 The `userId`, `itemId` or `sessionId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or the `portion` is not a real number from \[0.0,1.0\]. --- 404 The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- 409 A view portion of the exact same `userId`, `itemId`, and a greater or equal `timestamp` (or a greater `portion`) is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database. --- delete ### Delete View Portion Deletes an existing view portion specified by (`userId`, `itemId`, `sessionId`) from the database. ```js client.send(new requests.DeleteViewPortion(userId, itemId, { // optional parameters: sessionId: 'ABAD1D', // string })); ``` --- Since version 2.1.0 --- Calls Limit Per Minute 1000 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **2.1.0** ID of your database. --- userId String Located in: **query** Required: **Yes** Since version: **2.1.0** ID of the user who rated the item. --- itemId String Located in: **query** Required: **Yes** Since version: **2.1.0** ID of the item which was rated. --- sessionId String Located in: **query** Required: **No** Since version: **2.1.0** Identifier of a session. --- #### Responses 200 Successful operation. --- 400 Given `userId`, `itemId` or `sessionId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. --- 404 The `userId`, `itemId` or view portion with the given (`userId`, `itemId`, `sessionId`) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- get ### List Item View Portions Lists all the view portions of an item ever submitted by different users. ```js const result = await client.send(new requests.ListItemViewPortions(itemId)); ``` --- Since version 2.1.0 --- Calls Limit Per Minute 60 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **2.1.0** ID of your database. --- itemId String Located in: **path** Required: **Yes** Since version: **2.1.0** ID of the item whose view portions are to be listed. --- #### Responses 200 Successful operation. ``` [ { "itemId": "item-x", "userId": "user-a", "sessionId": "ABAD1D", "portion": 0.5, "autoPresented": true, "timeSpent": 40.5, "timestamp": 1348151906.0 }, { "itemId": "item-x", "userId": "user-b", "sessionId": null, "portion": 1, "autoPresented": false, "timeSpent": 0, "timestamp": 1348239363.0 } ] ``` --- 400 The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. --- 404 Given `itemId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. --- get ### List User View Portions Lists all the view portions ever submitted by the given user. ```js const result = await client.send(new requests.ListUserViewPortions(userId)); ``` --- Since version 2.1.0 --- Calls Limit Per Minute 60 --- #### Parameters databaseId String Located in: **path** Required: **Yes** Since version: **2.1.0** ID of your database. --- userId String Located in: **path** Required: **Yes** Since version: **2.1.0** ID of the user whose view portions are to be listed. --- #### Responses 200 Successful operation. ``` [ { "itemId": "item-x", "userId": "user-a", "sessionId": "ABAD1D", "portion": 0.25, "autoPresented": false, "timeSpent": 1.5, "timestamp": 1348151906.0 }, { "itemId": "item-y", "userId": "user-a", "sessionId": "EWQKOL", "portion": 0.1, "autoPresented": true, "timeSpent": 231.25, "timestamp": 1348239363.0 } ] ``` --- 400 The `userId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. --- 404 Given `userId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. ---