Get recommendations

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

{
  "object": "list",
  "message": "Recommendations fetched",
  "request_id": "c7f0d2bb-56b1-4ca7-8f09-84d8e4ed02b4",
  "url": "/v1/recommendations",
  "data": [
    {
      "id": "rec_itm_7f3a2c9e",
      "object": "recommendation",
      "item_id": "itm_7f3a2c9e",
      "rank": 1,
      "score": 0.94,
      "item": {
        "id": "itm_7f3a2c9e",
        "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>'

{
  "object": "list",
  "message": "Recommendations fetched",
  "request_id": "c7f0d2bb-56b1-4ca7-8f09-84d8e4ed02b4",
  "url": "/v1/recommendations",
  "data": [
    {
      "id": "rec_itm_7f3a2c9e",
      "object": "recommendation",
      "item_id": "itm_7f3a2c9e",
      "rank": 1,
      "score": 0.94,
      "item": {
        "id": "itm_7f3a2c9e",
        "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=usr_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`	string	no	Numeric console context ID such as `101`. Legacy `ctx_` aliases such as `ctx_101` are also accepted.
`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": "rec_itm_7f3a2c9e",
      "object": "recommendation",
      "item_id": "itm_7f3a2c9e",
      "rank": 1,
      "score": 0.94,
      "item": {
        "id": "itm_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

string

Numeric console context ID. Legacy ctx_ aliases such as ctx_101 are also accepted.

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

Show child attributes

section

object

Show child attributes

done

boolean

Present in auto mode.

experiments

object[]

Show child attributes

user_segments

string[]

pipeline_id

integer | null

Retrieve event

Documentation Index

​Description

​Request

​Response

​Errors

Authorizations

Headers

Query Parameters

Response

Description

Request

Response

Errors