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

# List Lead Insights

> Returns all Lead Insights (preferences) extracted for a lead.
Same data shown in the conversation UI under **Lead Insights**.

Path `{id}` here is the **lead id** (the numeric `id` from
`GET /api/leads`), not a preference document id.

Requires `conversations:view` permission.




## OpenAPI

````yaml GET /api/preferences/{id}
openapi: 3.1.0
info:
  title: Naturalead Lead Insights (Preferences) API
  version: 1.0.0
  description: >
    Lead Insights are structured key points the AI extracts from conversations

    (budget, timeline, location, etc.). They power the "Lead Insights" sidebar

    in the dashboard and are the recommended CRM sync payload for what the

    lead shared — more useful than a free-form conversation `summary`.


    Insights are **lead-scoped** (one set per lead, accumulated across
    sessions),

    not conversation-scoped. All endpoints require API key or Clerk auth and are

    scoped to the caller's account.


    Path note: `GET` uses the **lead id**; `PATCH` / `DELETE` use the
    **preference

    document `_id`**. Same URL pattern, different identifiers by method.
servers:
  - url: https://api.naturalead.ai
    description: Production
  - url: http://localhost:3001
    description: Local development
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Lead Insights
    description: Extracted lead preferences / key points for CRM sync and agent memory
paths:
  /api/preferences/{id}:
    get:
      tags:
        - Lead Insights
      summary: List Lead Insights
      description: |
        Returns all Lead Insights (preferences) extracted for a lead.
        Same data shown in the conversation UI under **Lead Insights**.

        Path `{id}` here is the **lead id** (the numeric `id` from
        `GET /api/leads`), not a preference document id.

        Requires `conversations:view` permission.
      operationId: listLeadPreferences
      parameters:
        - name: id
          in: path
          required: true
          description: |
            Lead id (same `id` returned by `GET /api/leads`), as a string path
            segment — e.g. `"42"`.
          schema:
            type: string
          example: '42'
      responses:
        '200':
          description: Lead insights for the lead (empty array if none yet).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LeadPreference'
              example:
                - _id: 507f1f77bcf86cd799439011
                  leadId: '42'
                  topic: budget
                  preference: $50k-100k
                  confidence: high
                  source: 'lead: Our budget is around 50 to 100k'
                  updatedAt: '2026-08-10T12:00:00.000Z'
                  createdAt: '2026-08-10T11:55:00.000Z'
                - _id: 507f1f77bcf86cd799439012
                  leadId: '42'
                  topic: timeline
                  preference: Q2 2026
                  confidence: medium
                  source: 'lead: Looking to decide by summer'
                  updatedAt: '2026-08-10T12:01:00.000Z'
                  createdAt: '2026-08-10T12:01:00.000Z'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    LeadPreference:
      type: object
      description: |
        A single extracted lead insight (preference). Unique per
        `(accountId, leadId, topic)` — updates overwrite the same topic.
      properties:
        _id:
          type: string
          description: Preference document id.
        leadId:
          type: string
          description: Lead id these insights belong to.
        accountId:
          type: string
          description: Owning account id.
        conversationId:
          type: string
          description: Conversation that last wrote or updated this insight.
        topic:
          type: string
          maxLength: 100
          description: Preference domain (e.g. budget, timeline, location).
        preference:
          type: string
          maxLength: 200
          description: Extracted value for the topic.
        confidence:
          type: string
          enum:
            - high
            - medium
            - low
          description: Model confidence in the extraction.
        source:
          type: string
          description: Short snippet or provenance of the extraction.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
          description: TTL expiry (default ~90 days from last write).
      required:
        - _id
        - leadId
        - topic
        - preference
        - confidence
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
      required:
        - error
  responses:
    InternalError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Failed to fetch preferences
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for programmatic access (format nl_live_* or nl_test_*)
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token using an API key (format nl_live_* or nl_test_*) or Clerk
        session

````