Recommendations

​

The basic request

curl "https://api.neuronsearchlab.com/v1/recommendations?user_id=user-123&context_id=101&limit=10" \
  -H "Authorization: Bearer <access_token>"

const result = await sdk.getRecommendations({ userId: "user-123", contextId: 101, limit: 10 });

$result = $sdk->getRecommendations(['userId' => 'user-123', 'contextId' => 101, 'limit' => 10]);

let result = try await sdk.getRecommendations(
  RecommendationOptions(userId: "user-123", contextId: 101, limit: 10)
)

​

The response

{
  "object": "list",
  "request_id": "c7f0d2bb-56b1-4ca7-8f09-84d8e4ed02b4",
  "data": [
    {
      "object": "recommendation",
      "item_id": 3187,
      "rank": 1,
      "score": 0.94,
      "item": {
        "id": 3187,
        "name": "Trail running shoes",
        "description": "Lightweight shoes with a waterproof upper.",
        "metadata": { "category": "footwear", "price": 120, "image_url": "https://…" }
      }
    }
  ],
  "has_more": true,
  "next_cursor": "…"
}

​

Common placements

​

New and anonymous visitors

• No history: the context falls back to popular, trending and fresh items, and to content similarity when there is an item_id or basket seed.
• Anonymous visitors: send a stable anonymous_id or a session-scoped user_id. When the visitor signs in, link the two identities so their earlier behaviour carries over. See Identity.
• Brand new catalogue: “more like this” works from item descriptions alone, before any events exist.

​

Several rails on one page

curl -X POST https://api.neuronsearchlab.com/v1/recommendations/batch \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123",
    "requests": [
      { "key": "for_you", "context_id": 101, "limit": 12 },
      { "key": "similar", "context_id": 102, "item_id": 3187, "limit": 6 }
    ]
  }'

const page = await sdk.getRecommendationSets({
  userId: "user-123",
  sets: [
    { key: "for_you", contextId: 101, limit: 12 },
    { key: "similar", contextId: 102, itemId: 3187, limit: 6 },
  ],
});
page.sets.for_you.data;        // items for that rail
page.sets.similar.request_id;  // send with events from that rail

• Up to eight sets per request; the SDKs split larger pages for you.
• Each set is billed as one recommendation request. Identical sets in one batch count once.
• A failed set reports its own status and error; the others still return.
• Use a stable request_id when retrying the same batch body so the service can reuse that batch. Do not reuse it for a different request. SDK calls split into several batches use additional request IDs; repeating the whole multi-batch call is not a guarantee that every chunk will be reused.

​

Paged and endless feeds

• Next page of one rail: pass starting_after (or the next_cursor from the last response).
• Endless feed of titled sections: getAutoRecommendations() (or mode=auto) returns one section at a time, such as “Because you liked Trail running shoes”, with a cursor for the next.

const section = await sdk.getAutoRecommendations({ userId: "user-123", limit: 6 });
section.section?.title; // "Because you liked Trail running shoes"
const next = await sdk.getAutoRecommendations({ userId: "user-123", cursor: section.next_cursor });

​

Handle failures

​

Next