> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuronsearchlab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get recommendations

> Retrieve personalized recommendations.

## 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

```http theme={null}
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`      | string  | no       | Numeric console context ID 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

```json theme={null}
{
  "object": "list",
  "url": "/v1/recommendations",
  "data": [
    {
      "id": "7f3a2c9e",
      "object": "recommendation",
      "item_id": "7f3a2c9e",
      "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       |


## OpenAPI

````yaml GET /v1/recommendations
openapi: 3.0.3
info:
  title: NeuronSearchLab Core API
  version: 1.0.0
  description: >-
    Versioned data-plane API for OAuth token exchange, catalog item ingestion,
    user event ingestion, and recommendation serving.
  license:
    name: Proprietary
    url: https://neuronsearchlab.com
servers:
  - url: https://api.neuronsearchlab.com
    description: Core API Gateway custom domain
security:
  - oauth2: []
tags:
  - name: Authentication
    description: OAuth 2.0 client credentials token exchange.
  - name: Items
    description: Catalog item ingestion, lookup, update, deletion, and pagination.
  - name: Events
    description: User interaction event ingestion, lookup, and pagination.
  - name: Recommendations
    description: >-
      Personalized recommendation serving, request-scoped filtering, and
      auto-section generation.
  - name: Search
    description: Query-driven search serving through the Core API data plane.
  - name: CORS
    description: Browser preflight routes generated by API Gateway.
paths:
  /v1/recommendations:
    get:
      tags:
        - Recommendations
      summary: Get recommendations
      description: >-
        Retrieve personalized recommendations. Requests can be narrowed with
        context IDs, request-scoped metadata filters, cursor pagination, and
        auto-section parameters.
      operationId: getRecommendations
      parameters:
        - name: X-Request-Id
          in: header
          description: >-
            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.
          schema:
            type: string
            format: uuid
        - name: X-Session-Id
          in: header
          description: >-
            Optional session identifier stored with served-recommendation
            telemetry.
          schema:
            type: string
        - name: X-Anonymous-Id
          in: header
          description: >-
            Optional anonymous identifier stored with served-recommendation
            telemetry when `user_id` is absent.
          schema:
            type: string
        - name: X-SDK
          in: header
          description: Optional SDK name stored with served-recommendation telemetry.
          schema:
            type: string
        - name: X-SDK-Version
          in: header
          description: Optional SDK version stored with served-recommendation telemetry.
          schema:
            type: string
        - name: X-Platform
          in: header
          description: >-
            Optional client platform stored with served-recommendation
            telemetry.
          schema:
            type: string
        - name: user_id
          in: query
          description: >-
            End-user identifier to personalize for. When omitted, the API falls
            back to the token subject.
          schema:
            type: string
          example: user-abc123
        - name: context_id
          in: query
          description: Numeric console context ID.
          schema:
            type: string
          example: '101'
        - $ref: '#/components/parameters/RecommendationLimit'
        - name: quantity
          in: query
          description: Legacy alias for `limit`.
          schema:
            type: integer
            minimum: 1
            maximum: 100
          deprecated: true
        - name: starting_after
          in: query
          description: >-
            Cursor from the previous page. Accepts a recommendation ID, item ID,
            or raw item entity ID.
          schema:
            type: string
          example: 7f3a2c9e
        - name: entity_type
          in: query
          description: Entity type for personalization. Defaults to `User`.
          schema:
            type: string
            enum:
              - User
              - Item
            default: User
        - name: name
          in: query
          description: Optional display name override for the request entity.
          schema:
            type: string
        - name: description
          in: query
          description: Optional description override for the request entity.
          schema:
            type: string
        - name: mode
          in: query
          description: >-
            Recommendation serving mode. `auto` chooses the next section from
            recent user activity and returns an auto cursor.
          schema:
            type: string
            enum:
              - single
              - auto
            default: single
        - name: cursor
          in: query
          description: Auto-mode cursor returned by a previous response.
          schema:
            type: string
        - name: window_days
          in: query
          description: Auto-mode activity lookback window in days. Defaults to 14.
          schema:
            type: integer
            minimum: 1
            default: 14
        - name: candidate_limit
          in: query
          description: >-
            Auto-mode maximum number of recent activity anchors to evaluate.
            Defaults to 50.
          schema:
            type: integer
            minimum: 1
            default: 50
        - name: served_cap
          in: query
          description: >-
            Auto-mode maximum number of served section keys retained in the
            cursor. Defaults to 50.
          schema:
            type: integer
            minimum: 1
            default: 50
        - name: scope
          in: query
          description: >-
            JSON-encoded request scope. Today only `filters` is honored, using
            objects with `column`, `operator`, `value`, and optional `logic`.
          schema:
            type: string
          example: >-
            {"filters":[{"column":"category","operator":"=","value":"electronics"}]}
        - name: filter
          in: query
          description: >-
            Metadata filter shorthand. Repeat the parameter to combine multiple
            filters. Examples: `category:electronics`, `type!=comment`,
            `OR:brand:Acme`.
          schema:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
          style: form
          explode: true
        - name: filters
          in: query
          description: Alias for repeated `filter` query parameters.
          schema:
            oneOf:
              - type: string
              - type: array
                items:
                  type: string
          style: form
          explode: true
        - name: request_id
          in: query
          description: >-
            Optional stable request ID. Prefer the `X-Request-Id` header when
            possible.
          schema:
            type: string
            format: uuid
        - name: requestId
          in: query
          description: CamelCase alias for `request_id`.
          schema:
            type: string
            format: uuid
        - name: session_id
          in: query
          description: >-
            Optional session identifier. Prefer the `X-Session-Id` header when
            possible.
          schema:
            type: string
        - name: sessionId
          in: query
          description: CamelCase alias for `session_id`.
          schema:
            type: string
        - name: anonymous_id
          in: query
          description: >-
            Optional anonymous identifier. Prefer the `X-Anonymous-Id` header
            when possible.
          schema:
            type: string
        - name: anonymousId
          in: query
          description: CamelCase alias for `anonymous_id`.
          schema:
            type: string
      responses:
        '200':
          description: Recommendation list
          headers:
            X-Request-Id:
              description: Stable request ID for attribution and retry correlation.
              schema:
                type: string
                format: uuid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationList'
              examples:
                single:
                  $ref: '#/components/examples/RecommendationList'
                auto:
                  $ref: '#/components/examples/AutoRecommendationList'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '500':
          $ref: '#/components/responses/Error500'
      security:
        - oauth2:
            - neuronsearchlab-api/read
components:
  parameters:
    RecommendationLimit:
      name: limit
      in: query
      description: >-
        Maximum number of recommendations to return. Defaults to 20 and is
        capped at 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
      example: 10
  schemas:
    RecommendationList:
      type: object
      required:
        - object
        - request_id
        - url
        - data
        - has_more
        - next_cursor
        - limit
        - recommendations
        - quantity
        - processing_time_ms
        - mode
      properties:
        object:
          type: string
          enum:
            - list
        message:
          type: string
          example: Recommendations fetched
        request_id:
          type: string
          format: uuid
        url:
          type: string
          example: /v1/recommendations
        data:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/Recommendation'
              - $ref: '#/components/schemas/RecommendationGroup'
        recommendations:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/Recommendation'
              - $ref: '#/components/schemas/RecommendationGroup'
        has_more:
          type: boolean
        next_cursor:
          type: string
          nullable: true
        limit:
          type: integer
          minimum: 1
          maximum: 100
        embedding_info:
          $ref: '#/components/schemas/EmbeddingInfo'
        cold_start_fallback_used:
          type: boolean
        explanation:
          $ref: '#/components/schemas/RecommendationRequestExplanation'
        quantity:
          type: integer
          minimum: 0
        excluded_viewed_items:
          type: object
          nullable: true
          properties:
            value:
              type: integer
              nullable: true
            unit:
              type: string
              nullable: true
            interval:
              type: string
              nullable: true
          additionalProperties: true
        processing_time_ms:
          type: integer
          minimum: 0
        mode:
          type: string
          enum:
            - single
            - auto
        section:
          type: object
          nullable: true
          properties:
            section_id:
              type: string
            title:
              type: string
            subtitle:
              type: string
            reason:
              $ref: '#/components/schemas/Object'
          additionalProperties: true
        done:
          type: boolean
          description: Present in auto mode.
        experiments:
          type: array
          items:
            $ref: '#/components/schemas/ExperimentAssignment'
        user_segments:
          type: array
          items:
            type: string
        pipeline_id:
          type: integer
          nullable: true
      additionalProperties: true
    Recommendation:
      type: object
      required:
        - id
        - object
        - item_id
        - rank
        - score
        - item
      properties:
        id:
          type: string
          pattern: ^rec_
          example: 7f3a2c9e
        object:
          type: string
          enum:
            - recommendation
        item_id:
          type: string
          example: 7f3a2c9e
        entity_id:
          type: string
          description: Raw item entity ID from the candidate source.
          example: 7f3a2c9e
        rank:
          type: integer
          minimum: 1
          example: 1
        score:
          type: number
          format: double
          example: 0.94
        name:
          type: string
          example: Wireless Headphones
        description:
          type: string
          example: Noise-cancelling Bluetooth headphones.
        metadata:
          $ref: '#/components/schemas/Metadata'
        source:
          type: string
          description: >-
            Candidate source, such as `model`, `trending_backfill`, or
            `exploration`.
          example: model
        item:
          $ref: '#/components/schemas/RecommendationItem'
        explanation:
          $ref: '#/components/schemas/RecommendationExplanation'
      additionalProperties: true
    RecommendationGroup:
      type: object
      required:
        - group
        - items
        - score
      properties:
        group:
          type: string
          description: Group key built from the active context `group_by` fields.
        items:
          type: array
          items:
            $ref: '#/components/schemas/Recommendation'
        score:
          type: number
          format: double
        similarity:
          type: number
          format: double
      additionalProperties: true
    EmbeddingInfo:
      type: object
      required:
        - source
        - used_default
        - default_reason
        - dimension
        - expected_dimension
      properties:
        source:
          type: string
          enum:
            - db
            - default
            - item
        used_default:
          type: boolean
        default_reason:
          type: string
          nullable: true
          description: >-
            Reason the default embedding was used, for example
            `no_db_embedding`.
        dimension:
          type: integer
          minimum: 0
        expected_dimension:
          type: integer
          example: 64
    RecommendationRequestExplanation:
      type: object
      properties:
        scope:
          type: string
          example: request
        note:
          type: string
        context:
          $ref: '#/components/schemas/ContextExplanation'
        pipeline:
          $ref: '#/components/schemas/PipelineExplanation'
        experiments:
          type: array
          items:
            $ref: '#/components/schemas/ExperimentAssignment'
        user_segments:
          type: array
          items:
            type: string
        embedding:
          $ref: '#/components/schemas/EmbeddingInfo'
      additionalProperties: true
    Object:
      type: object
      additionalProperties: true
    ExperimentAssignment:
      type: object
      properties:
        experiment_id:
          type: integer
        experiment_name:
          type: string
        variant_id:
          type: integer
        variant_name:
          type: string
      additionalProperties: true
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - not_found_error
                - conflict_error
                - rate_limit_error
                - api_error
            code:
              type: string
            message:
              type: string
            details: {}
            request_id:
              type: string
              format: uuid
          additionalProperties: true
    Metadata:
      type: object
      description: Arbitrary JSON object used for filtering, ranking, and debugging.
      additionalProperties: true
      example:
        category: electronics
        brand: Acme
        price: 10999
        currency: usd
    RecommendationItem:
      type: object
      required:
        - id
        - object
        - name
        - description
        - metadata
      properties:
        id:
          type: string
          example: 7f3a2c9e
        object:
          type: string
          enum:
            - item
        name:
          type: string
          example: Wireless Headphones
        description:
          type: string
          example: Noise-cancelling Bluetooth headphones.
        metadata:
          $ref: '#/components/schemas/Metadata'
      additionalProperties: true
    RecommendationExplanation:
      type: object
      properties:
        item_id:
          type: string
        rank:
          type: integer
        summary:
          type: string
        shown_because:
          type: array
          items:
            type: string
        source:
          type: string
        score:
          type: object
          properties:
            final:
              type: number
              nullable: true
            base:
              type: number
              nullable: true
            cosine_distance:
              type: number
              nullable: true
            retrieval:
              type: number
              nullable: true
            ranker:
              type: number
              nullable: true
          additionalProperties: true
        context:
          $ref: '#/components/schemas/ContextExplanation'
        embedding:
          type: object
          additionalProperties: true
        pipeline:
          $ref: '#/components/schemas/PipelineExplanation'
        rules:
          type: array
          items:
            $ref: '#/components/schemas/Object'
        experiments:
          type: array
          items:
            $ref: '#/components/schemas/ExperimentAssignment'
        user_segments:
          type: array
          items:
            type: string
      additionalProperties: true
    ContextExplanation:
      type: object
      properties:
        context_id:
          type: string
          nullable: true
        mode:
          type: string
          enum:
            - single
            - auto
        filters:
          type: array
          items:
            $ref: '#/components/schemas/Object'
        request_filters:
          type: array
          items:
            $ref: '#/components/schemas/ScopeFilter'
        group_by:
          type: array
          items:
            type: string
        exclude_viewed_items:
          type: object
          nullable: true
          properties:
            value:
              type: integer
              nullable: true
            unit:
              type: string
              nullable: true
            interval:
              type: string
              nullable: true
          additionalProperties: true
        auto_section:
          type: object
          nullable: true
          properties:
            section_id:
              type: string
            title:
              type: string
            subtitle:
              type: string
            reason:
              $ref: '#/components/schemas/Object'
          additionalProperties: true
      additionalProperties: true
    PipelineExplanation:
      type: object
      properties:
        id:
          type: integer
          nullable: true
        stages:
          type: array
          items:
            $ref: '#/components/schemas/PipelineStageTrace'
      additionalProperties: true
    ScopeFilter:
      type: object
      required:
        - column
        - operator
        - value
      properties:
        column:
          type: string
        operator:
          type: string
          description: Filter operator, such as `=`, `!=`, `<`, `>`, `LIKE`, or `ILIKE`.
        value:
          oneOf:
            - type: string
            - type: number
            - type: boolean
        logic:
          type: string
          enum:
            - AND
            - OR
      additionalProperties: true
    PipelineStageTrace:
      type: object
      properties:
        stage:
          type: string
        enabled:
          type: boolean
        status:
          type: string
        pipeline_id:
          type: integer
          nullable: true
        config:
          $ref: '#/components/schemas/Object'
        note:
          type: string
        item_events:
          type: array
          items:
            $ref: '#/components/schemas/Object'
      additionalProperties: true
  examples:
    RecommendationList:
      summary: Recommendation list
      value:
        object: list
        message: Recommendations fetched
        request_id: c7f0d2bb-56b1-4ca7-8f09-84d8e4ed02b4
        url: /v1/recommendations
        data:
          - id: 7f3a2c9e
            object: recommendation
            item_id: 7f3a2c9e
            rank: 1
            score: 0.94
            item:
              id: 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
    AutoRecommendationList:
      summary: Auto section response
      value:
        object: list
        message: Auto section generated
        request_id: c7f0d2bb-56b1-4ca7-8f09-84d8e4ed02b4
        url: /v1/recommendations
        data: []
        has_more: false
        next_cursor: >-
          eyJ2IjoxLCJ3aW5kb3dfZGF5cyI6MTQsInNlcnZlZCI6WyJyZWNlbnRfYWN0aXZpdHkiXX0
        limit: 10
        embedding_info:
          source: item
          used_default: false
          default_reason: null
          dimension: 64
          expected_dimension: 64
        cold_start_fallback_used: false
        explanation:
          scope: request
        recommendations: []
        quantity: 0
        excluded_viewed_items: null
        processing_time_ms: 128
        mode: auto
        section:
          section_id: recent_activity
          title: Based on your recent activity
          reason:
            type: recent_activity
            window_days: 14
        done: false
    ErrorValidation:
      summary: Validation error
      value:
        error:
          type: invalid_request_error
          code: validation_error
          message: Validation error
          details:
            fieldErrors:
              name:
                - Required
    ErrorUnauthorized:
      summary: Unauthorized
      value:
        error:
          type: authentication_error
          code: unauthorized_no_client_id_in_jwt
          message: 'Unauthorized: No client ID in JWT'
  responses:
    Error400:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            validation:
              $ref: '#/components/examples/ErrorValidation'
    Error401:
      description: Unauthenticated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unauthorized:
              $ref: '#/components/examples/ErrorUnauthorized'
    Error403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Error500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.neuronsearchlab.com/oauth2/token
          scopes:
            neuronsearchlab-api/read: Read recommendations, items, and events.
            neuronsearchlab-api/write: Create, update, and delete items; submit events.

````