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

# Get Perception

> The statement, positioning, claims, negative prompts and sources, and best quotes.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/perception
openapi: 3.1.0
info:
  description: >-
    Read-only access to one organization's brands, as the member who created the
    API key. Each key may make 120 requests a minute. Every error is an RFC 9457
    problem (`application/problem+json`) whose `code` names it.
  summary: Read your brands' AI visibility in Heralded.
  title: Heralded API
  version: '1'
servers:
  - url: https://api.heralded.ai
security: []
paths:
  /v1/brands/{brand_id}/perception:
    get:
      tags:
        - v1
      summary: Get Perception
      description: >-
        The statement, positioning, claims, negative prompts and sources, and
        best quotes.
      operationId: getPerception
      parameters:
        - in: path
          name: brand_id
          required: true
          schema:
            format: uuid
            title: Brand Id
            type: string
        - in: query
          name: engine
          required: false
          schema:
            anyOf:
              - enum:
                  - perplexity
                  - gemini
                  - openai
                  - google_aio
                  - ai_mode
                  - copilot
                  - claude
                type: string
              - type: 'null'
            title: Engine
        - in: query
          name: prompt
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            title: Prompt
        - in: query
          name: type
          required: false
          schema:
            anyOf:
              - enum:
                  - organic
                  - brand_specific
                  - competitor_comparison
                type: string
              - type: 'null'
            title: Type
        - in: query
          name: intent
          required: false
          schema:
            anyOf:
              - enum:
                  - educational
                  - problem
                  - comparison
                  - transactional
                type: string
              - type: 'null'
            title: Intent
        - in: query
          name: topic
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            title: Topic
        - in: query
          name: segment
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Segment
        - description: Include only scans up to this completed scan id.
          in: query
          name: as_of
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            description: Include only scans up to this completed scan id.
            title: As Of
        - in: query
          name: period
          required: false
          schema:
            default: 1w
            enum:
              - 1w
              - 4w
              - 12w
              - all
            title: Period
            type: string
        - in: query
          name: list_limit
          required: false
          schema:
            anyOf:
              - maximum: 100
                minimum: 1
                type: integer
              - type: 'null'
            title: List Limit
        - in: query
          name: prompts_offset
          required: false
          schema:
            default: 0
            minimum: 0
            title: Prompts Offset
            type: integer
        - in: query
          name: sources_offset
          required: false
          schema:
            default: 0
            minimum: 0
            title: Sources Offset
            type: integer
        - in: query
          name: pages_offset
          required: false
          schema:
            default: 0
            minimum: 0
            title: Pages Offset
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Perception'
          description: Successful Response
        '400':
          content:
            application/problem+json:
              example:
                code: invalid_cursor
                detail: The cursor is invalid or belongs to a different query.
                instance: example-request-id
                status: 400
                title: Bad Request
                type: about:blank
              schema:
                $ref: '#/components/schemas/Problem'
          description: The cursor is invalid or belongs to a different query.
        '401':
          content:
            application/problem+json:
              example:
                code: invalid_token
                detail: >-
                  The Authorization header carries no API key Heralded knows: it
                  is missing, mistyped, revoked or expired.
                instance: example-request-id
                status: 401
                title: Unauthorized
                type: about:blank
              schema:
                $ref: '#/components/schemas/Problem'
          description: No API key, or one that is unknown, revoked or expired.
          headers:
            WWW-Authenticate:
              schema:
                example: Bearer
                type: string
        '404':
          content:
            application/problem+json:
              example:
                code: not_found
                detail: Nothing here that this API key can read.
                instance: example-request-id
                status: 404
                title: Not Found
                type: about:blank
              schema:
                $ref: '#/components/schemas/Problem'
          description: No such brand or answer, or the key's owner cannot read it.
        '409':
          content:
            application/problem+json:
              example:
                code: workspace_archived
                detail: The API key's organization is archived.
                instance: example-request-id
                status: 409
                title: Conflict
                type: about:blank
              schema:
                $ref: '#/components/schemas/Problem'
          description: The API key's organization is archived.
        '422':
          content:
            application/problem+json:
              example:
                code: invalid_request
                detail: The request's parameters are invalid; `errors` names each one.
                errors:
                  - loc:
                      - query
                      - limit
                    msg: Input should be less than or equal to 100
                    type: less_than_equal
                instance: example-request-id
                status: 422
                title: Unprocessable Content
                type: about:blank
              schema:
                $ref: '#/components/schemas/ValidationProblem'
          description: A path or query parameter is invalid.
        '429':
          content:
            application/problem+json:
              example:
                code: rate_limited
                detail: >-
                  This caller is past its requests for the minute. Retry after
                  the seconds in Retry-After.
                instance: example-request-id
                rate_limit:
                  limit: 120
                  remaining: 0
                  reset: 60
                  window: 60
                status: 429
                title: Too Many Requests
                type: about:blank
              schema:
                $ref: '#/components/schemas/RateLimitProblem'
          description: The API key made more than 120 requests in the minute.
          headers:
            Retry-After:
              description: Seconds until the key may call again.
              schema:
                example: 60
                type: integer
      security:
        - apiKey: []
components:
  schemas:
    V1Perception:
      properties:
        best_quotes:
          items:
            $ref: '#/components/schemas/V1PerceptionBestQuote'
          title: Best Quotes
          type: array
        claims:
          items:
            $ref: '#/components/schemas/V1PerceptionClaimRow'
          title: Claims
          type: array
        domain:
          title: Domain
          type: string
        filters:
          $ref: '#/components/schemas/FigureFilters'
        menus:
          $ref: '#/components/schemas/PromptFilters'
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        negative_prompts:
          items:
            $ref: '#/components/schemas/V1PerceptionNegativePrompt'
          title: Negative Prompts
          type: array
        negative_prompts_total:
          title: Negative Prompts Total
          type: integer
        negative_sources:
          items:
            $ref: '#/components/schemas/V1PerceptionNegativeSource'
          title: Negative Sources
          type: array
        negative_sources_total:
          title: Negative Sources Total
          type: integer
        period:
          $ref: '#/components/schemas/V1Period'
        praised:
          $ref: '#/components/schemas/V1Figure'
        understood:
          $ref: '#/components/schemas/V1Figure'
        written:
          $ref: '#/components/schemas/V1PerceptionWrittenPieces'
      required:
        - meta
        - domain
        - period
        - filters
        - written
        - understood
        - praised
        - claims
        - negative_prompts
        - negative_sources
        - negative_prompts_total
        - negative_sources_total
        - best_quotes
        - menus
      title: V1Perception
      type: object
    Problem:
      description: |-
        An RFC 9457 problem. `type` is always `about:blank`, so `title` is the
        status's name, and `code` is what a client branches on.
      properties:
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        instance:
          default: ''
          title: Instance
          type: string
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          const: about:blank
          default: about:blank
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
      title: Problem
      type: object
    ValidationProblem:
      properties:
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ValidationIssue'
          title: Errors
          type: array
        instance:
          default: ''
          title: Instance
          type: string
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          const: about:blank
          default: about:blank
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
        - errors
      title: ValidationProblem
      type: object
    RateLimitProblem:
      properties:
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        instance:
          default: ''
          title: Instance
          type: string
        rate_limit:
          $ref: '#/components/schemas/RateLimitValues'
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          const: about:blank
          default: about:blank
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
        - rate_limit
      title: RateLimitProblem
      type: object
    V1PerceptionBestQuote:
      properties:
        answer_read_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Answer Read Id
        engine_id:
          title: Engine Id
          type: string
        prompt_text:
          title: Prompt Text
          type: string
        prompt_uid:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Prompt Uid
        quote:
          title: Quote
          type: string
      required:
        - quote
        - engine_id
        - prompt_uid
        - prompt_text
        - answer_read_id
      title: V1PerceptionBestQuote
      type: object
    V1PerceptionClaimRow:
      properties:
        key:
          title: Key
          type: string
        kind:
          enum:
            - category
            - audience
            - offer
            - difference
            - fact
          title: Kind
          type: string
        kind_label:
          title: Kind Label
          type: string
        quote:
          anyOf:
            - $ref: '#/components/schemas/V1PerceptionQuotedLine'
            - type: 'null'
        state:
          anyOf:
            - $ref: '#/components/schemas/V1PerceptionClaimState'
            - type: 'null'
        trend:
          $ref: '#/components/schemas/V1PerceptionClaimTrend'
        verdicts:
          $ref: '#/components/schemas/V1PerceptionVerdicts'
        wording:
          title: Wording
          type: string
      required:
        - key
        - kind
        - kind_label
        - wording
        - quote
        - verdicts
        - trend
        - state
      title: V1PerceptionClaimRow
      type: object
    FigureFilters:
      properties:
        engine:
          anyOf:
            - enum:
                - perplexity
                - gemini
                - openai
                - google_aio
                - ai_mode
                - copilot
                - claude
              type: string
            - type: 'null'
          title: Engine
        intent:
          anyOf:
            - enum:
                - educational
                - problem
                - comparison
                - transactional
              type: string
            - type: 'null'
          title: Intent
        prompt:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Prompt
        segment:
          anyOf:
            - type: string
            - type: 'null'
          title: Segment
        topic:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Topic
        type:
          anyOf:
            - enum:
                - organic
                - brand_specific
                - competitor_comparison
              type: string
            - type: 'null'
          title: Type
      required:
        - engine
        - prompt
        - type
        - intent
        - topic
        - segment
      title: FigureFilters
      type: object
    PromptFilters:
      description: >-
        What the toolbar's four menus offer, counted over every tracked prompt

        rather than over the page (PR-4). A menu built from one page of ten
        would

        hide the segment the eleventh row is in.
      properties:
        intents:
          items:
            $ref: '#/components/schemas/PromptFilterOption'
          title: Intents
          type: array
        segments:
          items:
            $ref: '#/components/schemas/PromptFilterOption'
          title: Segments
          type: array
        topics:
          items:
            $ref: '#/components/schemas/PromptFilterOption'
          title: Topics
          type: array
        types:
          items:
            $ref: '#/components/schemas/PromptFilterOption'
          title: Types
          type: array
      required:
        - segments
        - types
        - intents
        - topics
      title: PromptFilters
      type: object
    Meta:
      properties:
        data_as_of:
          anyOf:
            - $ref: '#/components/schemas/DataAsOf'
            - type: 'null'
        query:
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          title: Query
          type: object
      required:
        - query
        - data_as_of
      title: Meta
      type: object
    V1PerceptionNegativePrompt:
      properties:
        answers:
          title: Answers
          type: integer
        negative:
          title: Negative
          type: integer
        prompt_uid:
          format: uuid
          title: Prompt Uid
          type: string
        share:
          anyOf:
            - type: integer
            - type: 'null'
          title: Share
        state:
          enum:
            - measured
            - too_few_answers
          title: State
          type: string
        text:
          title: Text
          type: string
      required:
        - prompt_uid
        - text
        - negative
        - answers
        - state
        - share
      title: V1PerceptionNegativePrompt
      type: object
    V1PerceptionNegativeSource:
      properties:
        citations:
          title: Citations
          type: integer
        domain:
          title: Domain
          type: string
        passage:
          anyOf:
            - type: string
            - type: 'null'
          title: Passage
        state:
          anyOf:
            - $ref: '#/components/schemas/V1PerceptionPageState'
            - type: 'null'
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
        url:
          title: Url
          type: string
      required:
        - url
        - domain
        - title
        - type
        - passage
        - citations
        - state
      title: V1PerceptionNegativeSource
      type: object
    V1Period:
      properties:
        excluded_reports:
          title: Excluded Reports
          type: integer
        first_answer_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: First Answer At
        last_answer_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Last Answer At
        preset:
          enum:
            - 1w
            - 4w
            - 12w
            - all
          title: Preset
          type: string
        reports:
          title: Reports
          type: integer
      required:
        - preset
        - reports
        - first_answer_at
        - last_answer_at
        - excluded_reports
      title: V1Period
      type: object
    V1Figure:
      properties:
        answers:
          title: Answers
          type: integer
        change:
          anyOf:
            - $ref: '#/components/schemas/V1Change'
            - type: 'null'
        denominator:
          anyOf:
            - type: integer
            - type: 'null'
          title: Denominator
        high:
          anyOf:
            - type: integer
            - type: 'null'
          title: High
        low:
          anyOf:
            - type: integer
            - type: 'null'
          title: Low
        numerator:
          anyOf:
            - type: number
            - type: 'null'
          title: Numerator
        state:
          enum:
            - measured
            - too_few_answers
            - calibrating
            - first_report
            - not_comparable
            - not_measured
          title: State
          type: string
        trend:
          items:
            $ref: '#/components/schemas/V1TrendPoint'
          title: Trend
          type: array
        value:
          anyOf:
            - type: integer
            - type: 'null'
          title: Value
      required:
        - value
        - low
        - high
        - numerator
        - denominator
        - answers
        - state
        - change
        - trend
      title: V1Figure
      type: object
    V1PerceptionWrittenPieces:
      description: |-
        What the latest weekly report's interpretation wrote, over every
        answer and every engine: none of it follows the period or a filter.
      properties:
        line_to_own:
          anyOf:
            - type: string
            - type: 'null'
          title: Line To Own
        positioning:
          items:
            $ref: '#/components/schemas/V1PerceptionPositioningCell'
          title: Positioning
          type: array
        report_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Report At
        report_scan_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Report Scan Id
        statement:
          anyOf:
            - type: string
            - type: 'null'
          title: Statement
      required:
        - report_scan_id
        - report_at
        - statement
        - line_to_own
        - positioning
      title: V1PerceptionWrittenPieces
      type: object
    ValidationIssue:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Loc
          type: array
        msg:
          title: Msg
          type: string
        type:
          title: Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationIssue
      type: object
    RateLimitValues:
      properties:
        limit:
          title: Limit
          type: integer
        remaining:
          title: Remaining
          type: integer
        reset:
          title: Reset
          type: integer
        window:
          title: Window
          type: integer
      required:
        - limit
        - window
        - remaining
        - reset
      title: RateLimitValues
      type: object
    V1PerceptionQuotedLine:
      description: One answer's words on a claim, and how many answers reached its verdict.
      properties:
        answer_read_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Answer Read Id
        count:
          title: Count
          type: integer
        engine_id:
          title: Engine Id
          type: string
        prompt_uid:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Prompt Uid
        quote:
          title: Quote
          type: string
        verdict:
          enum:
            - agrees
            - partly
            - contradicts
            - doesnt_say
          title: Verdict
          type: string
      required:
        - verdict
        - quote
        - count
        - engine_id
        - prompt_uid
        - answer_read_id
      title: V1PerceptionQuotedLine
      type: object
    V1PerceptionClaimState:
      properties:
        action_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Action Id
        kind:
          enum:
            - new
            - action
            - resolved
          title: Kind
          type: string
        label:
          title: Label
          type: string
      required:
        - kind
        - label
        - action_id
      title: V1PerceptionClaimState
      type: object
    V1PerceptionClaimTrend:
      description: |-
        The change in the share of answers that contradict a claim, as the
        Trend column states it: a rise is bad.
      properties:
        delta:
          anyOf:
            - type: integer
            - type: 'null'
          title: Delta
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
        state:
          enum:
            - up
            - down
            - steady
            - calibrating
            - first_report
            - not_comparable
            - none
          title: State
          type: string
      required:
        - state
        - delta
        - label
      title: V1PerceptionClaimTrend
      type: object
    V1PerceptionVerdicts:
      properties:
        agrees:
          default: 0
          title: Agrees
          type: integer
        answers:
          default: 0
          title: Answers
          type: integer
        contradicts:
          default: 0
          title: Contradicts
          type: integer
        doesnt_say:
          default: 0
          title: Doesnt Say
          type: integer
        partly:
          default: 0
          title: Partly
          type: integer
      required:
        - agrees
        - partly
        - contradicts
        - doesnt_say
        - answers
      title: V1PerceptionVerdicts
      type: object
    PromptFilterOption:
      properties:
        count:
          title: Count
          type: integer
        label:
          title: Label
          type: string
        value:
          title: Value
          type: string
      required:
        - value
        - label
        - count
      title: PromptFilterOption
      type: object
    DataAsOf:
      properties:
        completed_at:
          format: date-time
          title: Completed At
          type: string
        id:
          format: uuid
          title: Id
          type: string
      required:
        - id
        - completed_at
      title: DataAsOf
      type: object
    JsonValue: {}
    V1PerceptionPageState:
      properties:
        action_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Action Id
        kind:
          enum:
            - new
            - action
            - yours
          title: Kind
          type: string
        label:
          title: Label
          type: string
      required:
        - kind
        - label
        - action_id
      title: V1PerceptionPageState
      type: object
    V1Change:
      properties:
        baseline:
          $ref: '#/components/schemas/V1Baseline'
        cells_unpaired:
          title: Cells Unpaired
          type: integer
        delta:
          anyOf:
            - type: number
            - type: 'null'
          title: Delta
        direction:
          enum:
            - up
            - down
            - steady
          title: Direction
          type: string
        high:
          anyOf:
            - type: number
            - type: 'null'
          title: High
        low:
          anyOf:
            - type: number
            - type: 'null'
          title: Low
        real:
          title: Real
          type: boolean
      required:
        - delta
        - low
        - high
        - real
        - direction
        - baseline
        - cells_unpaired
      title: V1Change
      type: object
    V1TrendPoint:
      properties:
        answers:
          title: Answers
          type: integer
        at:
          format: date-time
          title: At
          type: string
        break_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Break Label
        high:
          anyOf:
            - type: integer
            - type: 'null'
          title: High
        low:
          anyOf:
            - type: integer
            - type: 'null'
          title: Low
        state:
          enum:
            - measured
            - too_few_answers
            - calibrating
            - first_report
            - not_comparable
            - not_measured
          title: State
          type: string
        value:
          anyOf:
            - type: integer
            - type: 'null'
          title: Value
      required:
        - at
        - value
        - low
        - high
        - answers
        - state
        - break_label
      title: V1TrendPoint
      type: object
    V1PerceptionPositioningCell:
      properties:
        brand_key:
          title: Brand Key
          type: string
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
        engines:
          title: Engines
          type: integer
        is_you:
          title: Is You
          type: boolean
        line:
          anyOf:
            - type: string
            - type: 'null'
          title: Line
        name:
          title: Name
          type: string
      required:
        - brand_key
        - name
        - domain
        - is_you
        - engines
        - line
      title: V1PerceptionPositioningCell
      type: object
    V1Baseline:
      properties:
        first_answer_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: First Answer At
        last_answer_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Last Answer At
        reports:
          title: Reports
          type: integer
      required:
        - reports
        - first_answer_at
        - last_answer_at
      title: V1Baseline
      type: object
  securitySchemes:
    apiKey:
      description: 'An API key, sent as `Authorization: Bearer hrld_...`.'
      scheme: bearer
      type: http

````

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