Get recommendations

curl --request GET \
  --url https://api.neuronsearchlab.com/v1/recommendations \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.neuronsearchlab.com/v1/recommendations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.neuronsearchlab.com/v1/recommendations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.neuronsearchlab.com/v1/recommendations"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.neuronsearchlab.com/v1/recommendations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "object": "list",
  "message": "Recommendations fetched",
  "request_id": "c7f0d2bb-56b1-4ca7-8f09-84d8e4ed02b4",
  "url": "/v1/recommendations",
  "data": [
    {
      "id": 3187,
      "object": "recommendation",
      "item_id": 3187,
      "rank": 1,
      "score": 0.94,
      "item": {
        "id": 3187,
        "object": "item",
        "name": "Wireless Headphones",
        "description": "Noise-cancelling Bluetooth headphones.",
        "metadata": {
          "category": "electronics"
        }
      },
      "explanation": {
        "summary": "Ranked by vector similarity to the user's stored profile embedding.",
        "shown_because": [
          "Ranked by vector similarity to the user's stored profile embedding."
        ]
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "limit": 10,
  "embedding_info": {
    "source": "db",
    "used_default": false,
    "default_reason": null,
    "dimension": 64,
    "expected_dimension": 64
  },
  "cold_start_fallback_used": false,
  "explanation": {
    "scope": "request",
    "note": "Each recommendation item includes its own explanation object with source, score, pipeline, rules, experiments, and context."
  },
  "recommendations": [],
  "quantity": 1,
  "excluded_viewed_items": null,
  "processing_time_ms": 182,
  "mode": "single"
}

GET

recommendations

Get recommendations

curl --request GET \
  --url https://api.neuronsearchlab.com/v1/recommendations \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.neuronsearchlab.com/v1/recommendations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.neuronsearchlab.com/v1/recommendations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.neuronsearchlab.com/v1/recommendations"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.neuronsearchlab.com/v1/recommendations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "object": "list",
  "message": "Recommendations fetched",
  "request_id": "c7f0d2bb-56b1-4ca7-8f09-84d8e4ed02b4",
  "url": "/v1/recommendations",
  "data": [
    {
      "id": 3187,
      "object": "recommendation",
      "item_id": 3187,
      "rank": 1,
      "score": 0.94,
      "item": {
        "id": 3187,
        "object": "item",
        "name": "Wireless Headphones",
        "description": "Noise-cancelling Bluetooth headphones.",
        "metadata": {
          "category": "electronics"
        }
      },
      "explanation": {
        "summary": "Ranked by vector similarity to the user's stored profile embedding.",
        "shown_because": [
          "Ranked by vector similarity to the user's stored profile embedding."
        ]
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "limit": 10,
  "embedding_info": {
    "source": "db",
    "used_default": false,
    "default_reason": null,
    "dimension": 64,
    "expected_dimension": 64
  },
  "cold_start_fallback_used": false,
  "explanation": {
    "scope": "request",
    "note": "Each recommendation item includes its own explanation object with source, score, pipeline, rules, experiments, and context."
  },
  "recommendations": [],
  "quantity": 1,
  "excluded_viewed_items": null,
  "processing_time_ms": 182,
  "mode": "single"
}

Description

Returns ranked recommendation objects for a user or item. Pass context_id when the request should use a context configured in the console.

Request

GET /v1/recommendations?user_id=user-abc123&context_id=101&limit=10

Parameter	Type	Required	Description
`user_id`	string	no	End-user identifier. Falls back to the token subject when omitted.
`context_id`	integer	no	Context ID generated by the dashboard, such as `101`.
`limit`	integer	no	Number of recommendations to return. Defaults to `20`, maximum `100`.
`starting_after`	string	no	Cursor from the previous page. Accepts a recommendation ID or item ID.
`entity_type`	string	no	`User` or `Item`. Defaults to `User`.
`name`	string	no	Overrides the saved embedding display name.
`description`	string	no	Overrides the saved embedding description.
`filter`	string	no	Metadata filter shorthand. Repeat to combine filters.
`filters`	string	no	Alias for repeated `filter` query parameters.
`scope`	string	no	JSON-encoded request scope, currently honoring `filters`.
`mode`	string	no	`single` or `auto`. Defaults to `single`.
`cursor`	string	no	Auto-mode cursor from a previous response.
`window_days`	integer	no	Auto-mode recent activity lookback. Defaults to `14`.
`candidate_limit`	integer	no	Auto-mode anchor candidate count. Defaults to `50`.
`served_cap`	integer	no	Auto-mode served-section cursor cap. Defaults to `50`.
`request_id`	string	no	Stable request ID for attribution. Prefer the `X-Request-Id` header.
`session_id`	string	no	Session identifier for served-recommendation telemetry.
`anonymous_id`	string	no	Anonymous identifier for served-recommendation telemetry.

quantity remains accepted as a legacy alias for limit.

Response

{
  "object": "list",
  "url": "/v1/recommendations",
  "data": [
    {
      "id": "7f3a2c9e",
      "object": "recommendation",
      "item_id": 3187,
      "rank": 1,
      "score": 0.94,
      "item": {
        "id": "7f3a2c9e",
        "object": "item",
        "name": "Wireless Headphones",
        "description": "Noise-cancelling Bluetooth headphones.",
        "metadata": {
          "category": "electronics"
        }
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "limit": 10,
  "request_id": "c7f0d2bb-56b1-4ca7-8f09-84d8e4ed02b4",
  "processing_time_ms": 182
}

For backwards compatibility, the response also includes a recommendations field with the same result array. When a context enables grouping, data and recommendations contain grouped recommendation aggregates. Responses also include embedding_info, request-level explanation, and per-item explanation fields when available.

When searches steered the response

A user’s recent searches weigh into their recommendations like any other event. When they did, the response carries search_intent:

"search_intent": {
  "share": 0.29,
  "queries": [
    { "query": "waterproof trail shoes", "count": 2, "event_weight": 25, "share": 0.21, "last_searched_at": "2026-09-23T17:22:43Z" },
    { "query": "rain jacket", "count": 1, "event_weight": 25, "share": 0.08, "last_searched_at": "2026-09-22T09:10:02Z" }
  ],
  "candidates_added": 3,
  "candidates_rescored": 24
}

share is the searches’ share of the user’s recent event weight, and it is how far the ranking leaned towards them. Items added because they match a search have source: "search_intent", and their explanation names the search. The request-level explanation has a search_intent pipeline stage that says why it did or did not apply. Searches are read for user_id, or anonymous_id when there is no user_id.

Errors

Status	Scenario
`400`	Validation failed, malformed filter, or malformed pagination cursor
`401`	Missing/invalid access token or tenant resolution failed
`403`	Token does not include `neuronsearchlab-api/read`
`500`	Unexpected recommendation, database, or model-serving failure

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

X-Request-Id

string<uuid>

Optional stable request ID for retries and downstream event attribution. The same ID is returned in the response body and X-Request-Id response header.

X-Session-Id

string

Optional session identifier stored with served-recommendation telemetry.

X-Anonymous-Id

string

Optional anonymous identifier stored with served-recommendation telemetry when user_id is absent.

X-SDK

string

Optional SDK name stored with served-recommendation telemetry.

X-SDK-Version

string

Optional SDK version stored with served-recommendation telemetry.

X-Platform

string

Optional client platform stored with served-recommendation telemetry.

Query Parameters

user_id

string

End-user identifier to personalize for. When omitted, the API falls back to the token subject.

context_id

integer

Numeric console context ID.

Required range: x >= 1

limit

integer

default:20

Maximum number of recommendations to return. Defaults to 20 and is capped at 100.

Required range: 1 <= x <= 100

quantity

integer

Legacy alias for limit.

Required range: 1 <= x <= 100

starting_after

string

Cursor from the previous page. Accepts a recommendation ID, item ID, or raw item entity ID.

entity_type

enum<string>

default:User

Entity type for personalization. Defaults to User.

Available options:

User,

Item

name

string

Optional display name override for the request entity.

description

string

Optional description override for the request entity.

mode

enum<string>

default:single

Recommendation serving mode. auto chooses the next section from recent user activity and returns an auto cursor.

Available options:

single,

auto

cursor

string

Auto-mode cursor returned by a previous response.

window_days

integer

default:14

Auto-mode activity lookback window in days. Defaults to 14.

Required range: x >= 1

candidate_limit

integer

default:50

Auto-mode maximum number of recent activity anchors to evaluate. Defaults to 50.

Required range: x >= 1

served_cap

integer

default:50

Auto-mode maximum number of served section keys retained in the cursor. Defaults to 50.

Required range: x >= 1

scope

string

JSON-encoded request scope. Today only filters is honored, using objects with column, operator, value, and optional logic.

filter

Metadata filter shorthand. Repeat the parameter to combine multiple filters. Examples: category:electronics, type!=comment, OR:brand:Acme.

filters

Alias for repeated filter query parameters.

request_id

string<uuid>

Optional stable request ID. Prefer the X-Request-Id header when possible.

requestId

string<uuid>

CamelCase alias for request_id.

session_id

string

Optional session identifier. Prefer the X-Session-Id header when possible.

sessionId

string

CamelCase alias for session_id.

anonymous_id

string

Optional anonymous identifier. Prefer the X-Anonymous-Id header when possible.

anonymousId

string

CamelCase alias for anonymous_id.

Response

Recommendation list

object

enum<string>

required

Available options:

list

request_id

string<uuid>

required

url

string

required

Example:

"/v1/recommendations"

data

object[]

required

Option 1
Option 2

Show child attributes

recommendations

object[]

required

Option 1
Option 2

Show child attributes

has_more

boolean

required

next_cursor

string | null

required

limit

integer

required

Required range: 1 <= x <= 100

quantity

integer

required

Required range: x >= 0

processing_time_ms

integer

required

Required range: x >= 0

mode

enum<string>

required

Available options:

single,

auto

message

string

Example:

"Recommendations fetched"

embedding_info

object

Show child attributes

cold_start_fallback_used

boolean

explanation

object

Show child attributes

excluded_viewed_items

object | null

Show child attributes

section

object | null

Show child attributes

done

boolean

Present in auto mode.

experiments

object[]

Show child attributes

user_segments

string[]

pipeline_id

integer | null

search_intent

object

Present when the user's recent searches steered this response. Searches from the last 14 days are weighed against item events by event weight, each halving every 72 hours.

Show child attributes

Overview

Authentication

Items

Events

Recommendations

Search

Get recommendations

Description

Request

Response

When searches steered the response

Errors

Authorizations

Headers

Query Parameters

Response

​Description

​Request

​Response

​When searches steered the response

​Errors

Authorizations

Headers

Query Parameters

Response

Description

Request

Response

When searches steered the response

Errors