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.

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

Overview

Authentication

Items

Events

Recommendations

Search

Get recommendations

Description

Request

Response

Errors

Authorizations

Headers

Query Parameters

Response

​Description

​Request

​Response

​Errors

Authorizations

Headers

Query Parameters

Response

Description

Request

Response

Errors