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

# List insights

> The Insights board. What customers said about your product, sales, success, and market, tied to the account that said it. Only sorted insights linked to an account appear, never lines your own team said. Newest first. Unknown query parameters return 400.

What customers said about your product, sales, success, and market, tied to the account that said it. This is the same set the Insights board in the app shows. Only sorted insights linked to an account appear, newest first. Lines your own team said are left out.

Each insight has one `lane` (who has to act) and one `subtype` (what kind of work). The response carries the workspace's `taxonomy`, so you can label results without hardcoding it.

| Lane | Subtype | Label | Covers |
| - | - | - | - |
| `product` | `bug` | Bug | Something in the product is broken or fails. |
| `product` | `friction` | Friction | It works, but it is manual, slow, clunky, or confusing. |
| `product` | `feature` | Feature request | A capability you do not have. |
| `sales` | `objection` | Objection | A reason against buying, switching, or renewing, other than price. |
| `sales` | `pricing` | Pricing | Cost, fees, discounts, value for money. |
| `sales` | `pitch` | Pitch & messaging | The buyer misunderstood or questioned what you do or how you framed it. |
| `success` | `setup` | Setup | Getting it running. Install, integrations, logins, access. |
| `success` | `training` | Training & adoption | Staff not using it, or needing training or follow-up. |
| `market` | `partners` | Competitors & partners | Other vendors, incumbent tools, partners. Know, don't fix. |
| `market` | `buyers` | Who buys | Roles, decision makers, segments. Know, don't fix. |

Service businesses get service labels on the same keys. For example `bug` reads "Missed results" and `feature` reads "Service request". Read `taxonomy` for the labels your workspace uses.

New insights reach the board once they are sorted. Until then they do not appear here.


## OpenAPI

````yaml GET /v2/insights
openapi: 3.1.0
info:
  title: OpenNous REST API
  version: 2.0.0
  description: >-
    Read and write the OpenNous revenue context graph over HTTP. Authenticate
    with a workspace API key.
servers:
  - url: https://api.opennous.cloud
    description: OpenNous Cloud
security:
  - bearerAuth: []
  - apiKeyHeader: []
tags:
  - name: People
  - name: Accounts
  - name: Deals
  - name: Notes
  - name: Attention
  - name: Insights
  - name: Enrich & score
  - name: Organization
  - name: Workflows
  - name: Webhooks
    description: >-
      Subscribe to events and have them pushed to your own stack, with the
      account record attached.
  - name: Usage
paths:
  /v2/insights:
    get:
      tags:
        - Insights
      summary: List insights
      description: >-
        The Insights board. What customers said about your product, sales,
        success, and market, tied to the account that said it. Only sorted
        insights linked to an account appear, never lines your own team said.
        Newest first. Unknown query parameters return 400.
      operationId: listInsights
      parameters:
        - name: lane
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/InsightLane'
          description: Who has to act.
        - name: subtype
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/InsightSubtype'
          description: What kind of work. Must belong to `lane` when both are set.
        - name: focus
          in: query
          required: false
          schema:
            type: string
          description: >-
            Only insights from one account. Email, LinkedIn URL, domain, or
            entity UUID. A bare name returns 400.
        - name: since
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Only insights on or after this ISO date, for example `2026-09-01`.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 200
          description: Page size.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
          description: Rows to skip.
      responses:
        '200':
          description: A page of insights and the workspace taxonomy.
          content:
            application/json:
              schema:
                type: object
                properties:
                  insights:
                    type: array
                    items:
                      $ref: '#/components/schemas/Insight'
                  limit:
                    type: integer
                  offset:
                    type: integer
                  has_more:
                    type: boolean
                  taxonomy:
                    $ref: '#/components/schemas/InsightTaxonomy'
              example:
                insights:
                  - id: 5d0c2b7e-1f3a-4c8d-9e6b-2a7f4c1d8e30
                    lane: product
                    subtype: feature
                    content: Wants CRM sync to write call notes back to HubSpot.
                    quote: If it doesn't land in HubSpot, my reps won't see it.
                    speaker: Sarah Chen
                    account:
                      entity_id: 3e7a1d52-8c4b-4b9e-a0f3-6d2c9e8b7a15
                      name: Acme
                    source_ref: source://fireflies/01J8ZK2
                    occurred_at: '2026-09-24T15:00:00Z'
                    tags:
                      - CRM integration
                limit: 50
                offset: 0
                has_more: false
                taxonomy:
                  lanes:
                    - key: product
                      label: Product
                    - key: sales
                      label: Sales
                    - key: success
                      label: Customer success
                    - key: market
                      label: Market
                  subtypes:
                    - key: bug
                      lane: product
                      label: Bug
                      definition: something in our product is broken or fails
                    - key: friction
                      lane: product
                      label: Friction
                      definition: >-
                        it works, but it is manual, slow, clunky or confusing to
                        use
                    - key: feature
                      lane: product
                      label: Feature request
                      definition: they want a capability we do not have
                    - key: objection
                      lane: sales
                      label: Objection
                      definition: >-
                        a reason the buyer gives against buying, switching or
                        renewing with us, other than price
                    - key: pricing
                      lane: sales
                      label: Pricing
                      definition: cost, fees, per-use charges, discounts, value for money
                    - key: pitch
                      lane: sales
                      label: Pitch & messaging
                      definition: >-
                        the buyer misunderstood or questioned what we are or do,
                        or reacted to how we framed it
                    - key: setup
                      lane: success
                      label: Setup
                      definition: >-
                        getting it running: install, integrations to switch on,
                        logins, access, provisioning
                    - key: training
                      lane: success
                      label: Training & adoption
                      definition: >-
                        staff not using it, needing training, materials,
                        champions or follow-up
                    - key: partners
                      lane: market
                      label: Competitors & partners
                      definition: >-
                        other vendors and incumbent tools, partners, and the
                        rules they set
                    - key: buyers
                      lane: market
                      label: Who buys
                      definition: >-
                        roles, decision makers, customer segments and how
                        customers operate
        '400':
          description: A bad parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unknown_query_param:
                  summary: unknown_query_param
                  value:
                    error: unknown_query_param
                    detail: 'unsupported query param(s): type'
                    supported:
                      - lane
                      - subtype
                      - focus
                      - since
                      - limit
                      - offset
                      - category
                invalid_lane:
                  summary: invalid_lane
                  value:
                    error: invalid_lane
                    supported:
                      - product
                      - sales
                      - success
                      - market
                invalid_subtype:
                  summary: invalid_subtype
                  value:
                    error: invalid_subtype
                    supported:
                      - bug
                      - friction
                      - feature
                      - objection
                      - pricing
                      - pitch
                      - setup
                      - training
                      - partners
                      - buyers
                subtype_not_in_lane:
                  summary: subtype_not_in_lane
                  value:
                    error: subtype_not_in_lane
                    detail: '''pricing'' belongs to the ''sales'' lane, not ''product'''
                invalid_since:
                  summary: invalid_since
                  value:
                    error: invalid_since
                    detail: since must be an ISO date, e.g. 2026-09-01
                invalid_focus:
                  summary: invalid_focus
                  value:
                    error: invalid_focus
                    detail: >-
                      provide an entity id, email, LinkedIn URL, or domain — not
                      a bare name
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/UpgradeRequired'
        '404':
          description: '`focus` matches no account visible to this key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: focus_not_found
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          description: The Insights board is not set up on this instance yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: insights_board_not_ready
components:
  schemas:
    InsightLane:
      type: string
      enum:
        - product
        - sales
        - success
        - market
    InsightSubtype:
      type: string
      enum:
        - bug
        - friction
        - feature
        - objection
        - pricing
        - pitch
        - setup
        - training
        - partners
        - buyers
    Insight:
      type: object
      properties:
        id:
          type: string
          format: uuid
        lane:
          $ref: '#/components/schemas/InsightLane'
        subtype:
          $ref: '#/components/schemas/InsightSubtype'
        content:
          type: string
          description: The insight as one statement.
        quote:
          type:
            - string
            - 'null'
        speaker:
          type:
            - string
            - 'null'
        account:
          type:
            - object
            - 'null'
          properties:
            entity_id:
              type: string
              format: uuid
            name:
              type:
                - string
                - 'null'
        source_ref:
          type:
            - string
            - 'null'
          description: The call or message the insight came from.
        occurred_at:
          type:
            - string
            - 'null'
          format: date-time
        tags:
          type: array
          items:
            type: string
    InsightTaxonomy:
      type: object
      properties:
        lanes:
          type: array
          items:
            type: object
            properties:
              key:
                $ref: '#/components/schemas/InsightLane'
              label:
                type: string
        subtypes:
          type: array
          items:
            type: object
            properties:
              key:
                $ref: '#/components/schemas/InsightSubtype'
              lane:
                $ref: '#/components/schemas/InsightLane'
              label:
                type: string
              definition:
                type: string
    Error:
      type: object
      description: >-
        Every error response. `error` is a stable machine code. Some errors add
        fields such as `detail`, `supported`, `max`, or `reason`.
      required:
        - error
      properties:
        error:
          type: string
          description: Machine-readable error code.
        detail:
          type: string
          description: Human-readable explanation, when there is one.
      additionalProperties: true
  responses:
    Unauthorized:
      description: Missing, unknown, or expired API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              summary: api_key_required
              value:
                error: api_key_required
            invalid:
              summary: invalid_api_key
              value:
                error: invalid_api_key
            expired:
              summary: api_key_expired
              value:
                error: api_key_expired
                detail: >-
                  This API key has expired. Create or rotate a key to get a
                  fresh one.
    UpgradeRequired:
      description: The workspace is past its monthly operations limit and grace window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: upgrade_required
            reason: ops_limit_reached
            current_plan: starter
            upgrade_url: /settings?section=billing
    RateLimited:
      description: More than 600 requests in a minute on this key.
      headers:
        RateLimit-Limit:
          schema:
            type: integer
          description: Requests allowed per window.
        RateLimit-Remaining:
          schema:
            type: integer
          description: Requests left in the window.
        RateLimit-Reset:
          schema:
            type: integer
          description: Seconds until the window resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: rate_limited
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal_error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Workspace API key. Create one in **Settings → API keys**.
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: The same key, sent as a header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.