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

# List perceptions of a product in AI answers

> Returns the perception labels answer engines attach to the product over the timeframe, grouped by label and sentiment (positive, neutral, negative), most frequent first, with the answer engines that said it, the last time it was seen, and a sample quote. Filter by sentiment or search the label.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/products/{productId}/perceptions
openapi: 3.1.0
info:
  title: The Prompting Company API
  version: 0.1.0
  description: >-
    Machine-readable contract for The Prompting Company organization-scoped API
    routes.
  contact:
    name: The Prompting Company
    url: https://promptingcompany.com/support
    email: support@promptingcompany.com
  license:
    name: Proprietary
    url: https://promptingcompany.com/terms
  termsOfService: https://promptingcompany.com/terms
servers:
  - url: https://app.promptingco.com
    description: Production
  - url: http://localhost:3000
    description: Local development
security: []
tags:
  - name: Visibility & Mentions
  - name: Knowledge
  - name: Content
  - name: Simulations
  - name: Apps & Publishing
  - name: Products
  - name: Service Status
  - name: Account
paths:
  /api/v1/products/{productId}/perceptions:
    get:
      tags:
        - Visibility & Mentions
      summary: List perceptions of a product in AI answers
      description: >-
        Returns the perception labels answer engines attach to the product over
        the timeframe, grouped by label and sentiment (positive, neutral,
        negative), most frequent first, with the answer engines that said it,
        the last time it was seen, and a sample quote. Filter by sentiment or
        search the label.
      operationId: getProductsProductIdPerceptions
      parameters:
        - schema:
            type: string
            minLength: 1
          required: true
          name: productId
          in: path
        - schema:
            type: string
            enum:
              - 7d
              - 30d
              - 90d
            default: 30d
          required: false
          name: timeframe
          in: query
        - schema:
            type: string
            minLength: 1
          required: false
          name: regionId
          in: query
        - schema:
            type:
              - integer
              - 'null'
            minimum: 0
            maximum: 100000
            default: 0
          required: false
          name: page
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
          required: false
          name: pageSize
          in: query
        - schema:
            type: string
            enum:
              - positive
              - neutral
              - negative
          required: false
          name: sentiment
          in: query
        - schema:
            type: string
            maxLength: 200
          required: false
          name: search
          in: query
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      total:
                        type: integer
                      page:
                        type: integer
                      pageSize:
                        type: integer
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            label:
                              type: string
                            sentiment:
                              type: string
                              enum:
                                - positive
                                - neutral
                                - negative
                            count:
                              type: integer
                            models:
                              type: array
                              items:
                                type: string
                            lastSeen:
                              type: string
                            quote:
                              type: string
                          required:
                            - label
                            - sentiment
                            - count
                            - models
                            - lastSeen
                            - quote
                    required:
                      - total
                      - page
                      - pageSize
                      - items
                required:
                  - ok
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    enum:
                      - false
                  code:
                    type: string
                  message:
                    type: string
                  details: {}
                required:
                  - ok
                  - code
                  - message
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    enum:
                      - false
                  code:
                    type: string
                  message:
                    type: string
                  details: {}
                required:
                  - ok
                  - code
                  - message
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    enum:
                      - false
                  code:
                    type: string
                  message:
                    type: string
                  details: {}
                required:
                  - ok
                  - code
                  - message
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    enum:
                      - false
                  code:
                    type: string
                  message:
                    type: string
                  details: {}
                required:
                  - ok
                  - code
                  - message
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    enum:
                      - false
                  code:
                    type: string
                  message:
                    type: string
                  details: {}
                required:
                  - ok
                  - code
                  - message
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    enum:
                      - false
                  code:
                    type: string
                  message:
                    type: string
                  details: {}
                required:
                  - ok
                  - code
                  - message
      security:
        - apiKeyAuth: []
        - bearerAuth: []
        - cookieAuth: []
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Organization-scoped API key. Available scopes:

        - content:read: Read site pages, markdown content, and llms.txt files

        - content:write: Create, update, and delete site pages and content

        - prompts:read: Read prompts, topics, Radar topics, prompt suggestions,
        and prompt analysis results

        - prompts:write: Create, update, archive prompts and generate, edit, or
        review prompt suggestions

        - simulations:read: Read agent-simulation tasks, runs, environments, and
        analytics

        - simulations:write: Create and trigger simulation runs

        - logs:read: Read AI-traffic logs and request-level audit events

        - analytics:read: Read analytics aggregates (rankings, mentions,
        sources, SOV)

        - analytics:write: Write events to analytics

        - products:read: Read product metadata and competitor data

        - products:write: Update product settings and competitor lists
      x-scopes:
        content:read: Read site pages, markdown content, and llms.txt files
        content:write: Create, update, and delete site pages and content
        prompts:read: >-
          Read prompts, topics, Radar topics, prompt suggestions, and prompt
          analysis results
        prompts:write: >-
          Create, update, archive prompts and generate, edit, or review prompt
          suggestions
        simulations:read: Read agent-simulation tasks, runs, environments, and analytics
        simulations:write: Create and trigger simulation runs
        logs:read: Read AI-traffic logs and request-level audit events
        analytics:read: Read analytics aggregates (rankings, mentions, sources, SOV)
        analytics:write: Write events to analytics
        products:read: Read product metadata and competitor data
        products:write: Update product settings and competitor lists
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer session or OAuth access token. Available OAuth scopes:

        - content:read: Read site pages, markdown content, and llms.txt files

        - content:write: Create, update, and delete site pages and content

        - prompts:read: Read prompts, topics, Radar topics, prompt suggestions,
        and prompt analysis results

        - prompts:write: Create, update, archive prompts and generate, edit, or
        review prompt suggestions

        - simulations:read: Read agent-simulation tasks, runs, environments, and
        analytics

        - simulations:write: Create and trigger simulation runs

        - logs:read: Read AI-traffic logs and request-level audit events

        - analytics:read: Read analytics aggregates (rankings, mentions,
        sources, SOV)

        - analytics:write: Write events to analytics

        - products:read: Read product metadata and competitor data

        - products:write: Update product settings and competitor lists
      x-scopes:
        content:read: Read site pages, markdown content, and llms.txt files
        content:write: Create, update, and delete site pages and content
        prompts:read: >-
          Read prompts, topics, Radar topics, prompt suggestions, and prompt
          analysis results
        prompts:write: >-
          Create, update, archive prompts and generate, edit, or review prompt
          suggestions
        simulations:read: Read agent-simulation tasks, runs, environments, and analytics
        simulations:write: Create and trigger simulation runs
        logs:read: Read AI-traffic logs and request-level audit events
        analytics:read: Read analytics aggregates (rankings, mentions, sources, SOV)
        analytics:write: Write events to analytics
        products:read: Read product metadata and competitor data
        products:write: Update product settings and competitor lists
    cookieAuth:
      type: apiKey
      in: cookie
      name: better-auth.session_token
      description: First-party browser session cookie.

````

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