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

> The engines' answers, newest first, optionally for one prompt, engine or named brand.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/answers
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}/answers:
    get:
      tags:
        - v1
      summary: Get Answers
      description: >-
        The engines' answers, newest first, optionally for one prompt, engine or
        named brand.
      operationId: listAnswers
      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: limit
          required: false
          schema:
            default: 20
            maximum: 100
            minimum: 1
            title: Limit
            type: integer
        - in: query
          name: offset
          required: false
          schema:
            default: 0
            minimum: 0
            title: Offset
            type: integer
        - in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - maxLength: 4096
                type: string
              - type: 'null'
            title: Cursor
        - description: Weekly-report period; omitted for all weekly and daily answers.
          in: query
          name: period
          required: false
          schema:
            anyOf:
              - enum:
                  - 1w
                  - 4w
                  - 12w
                  - all
                type: string
              - type: 'null'
            description: Weekly-report period; omitted for all weekly and daily answers.
            title: Period
        - in: query
          name: prompt_id
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            title: Prompt Id
        - description: Only answers that name this brand, such as a rival's name.
          in: query
          name: names
          required: false
          schema:
            anyOf:
              - maxLength: 200
                type: string
              - type: 'null'
            description: Only answers that name this brand, such as a rival's name.
            title: Names
        - in: query
          name: you
          required: false
          schema:
            anyOf:
              - enum:
                  - named
                  - recommended
                  - not_named
                type: string
              - type: 'null'
            title: You
        - in: query
          name: cites
          required: false
          schema:
            anyOf:
              - maxLength: 4096
                type: string
              - type: 'null'
            title: Cites
        - in: query
          name: source_group
          required: false
          schema:
            anyOf:
              - enum:
                  - own
                  - rival
                  - review
                  - editorial
                  - community
                  - vendor
                  - other
                type: string
              - const: independent
                type: string
              - type: 'null'
            title: Source Group
        - in: query
          name: cited_page
          required: false
          schema:
            anyOf:
              - maxLength: 4096
                type: string
              - type: 'null'
            title: Cited Page
        - in: query
          name: claim
          required: false
          schema:
            anyOf:
              - maxLength: 1000
                type: string
              - type: 'null'
            title: Claim
        - in: query
          name: claim_wording
          required: false
          schema:
            anyOf:
              - maxLength: 4096
                type: string
              - type: 'null'
            title: Claim Wording
        - in: query
          name: content_topic
          required: false
          schema:
            anyOf:
              - maxLength: 1000
                type: string
              - type: 'null'
            title: Content Topic
        - in: query
          name: action
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            title: Action
        - in: query
          name: search
          required: false
          schema:
            anyOf:
              - maxLength: 1000
                type: string
              - type: 'null'
            title: Search
        - in: query
          name: sort
          required: false
          schema:
            default: time
            enum:
              - time
              - sources
            title: Sort
            type: string
        - in: query
          name: direction
          required: false
          schema:
            default: desc
            enum:
              - asc
              - desc
            title: Direction
            type: string
        - in: query
          name: with_menus
          required: false
          schema:
            default: false
            title: With Menus
            type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Answers'
          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:
    V1Answers:
      examples:
        - answers:
            - engine: openai
              excerpt: For agencies, Acme and Rival lead...
              id: 5d2e8c1f-7a3b-4c6d-9e0f-1a2b3c4d5e6f
              mentioned: true
              prompt: best crm for agencies
              prompt_id: 0b8e5f7a-2c4d-4e6f-8a1b-3c5d7e9f1a2b
              read_at: '2026-09-22T09:00:00Z'
              recommended: true
              segment: Agencies
          limit: 20
          offset: 0
          total: 1
      properties:
        answers:
          items:
            $ref: '#/components/schemas/V1AnswerSummary'
          title: Answers
          type: array
        cited_page_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Cited Page Key
        cited_page_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Cited Page Label
        engine_vocabulary:
          items:
            $ref: '#/components/schemas/EngineVocabulary'
          title: Engine Vocabulary
          type: array
        filter_options:
          $ref: '#/components/schemas/AnswerFilterOptions'
        has_more:
          default: false
          title: Has More
          type: boolean
        limit:
          title: Limit
          type: integer
        menus:
          anyOf:
            - $ref: '#/components/schemas/PromptFilters'
            - type: 'null'
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        named_count:
          default: 0
          title: Named Count
          type: integer
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Pass as cursor with the same query to read the next page; null at
            the end.
          title: Next Cursor
        offset:
          title: Offset
          type: integer
        period:
          anyOf:
            - $ref: '#/components/schemas/V1Period'
            - type: 'null'
        recommended_count:
          default: 0
          title: Recommended Count
          type: integer
        source_group_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Group Label
        summary_sentence:
          default: ''
          title: Summary Sentence
          type: string
        total:
          title: Total
          type: integer
      required:
        - meta
        - next_cursor
        - total
        - limit
        - offset
        - answers
        - engine_vocabulary
        - period
        - has_more
        - named_count
        - recommended_count
        - summary_sentence
        - filter_options
        - source_group_label
        - cited_page_label
        - cited_page_key
        - menus
      title: V1Answers
      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
    V1AnswerSummary:
      properties:
        also_named:
          items:
            $ref: '#/components/schemas/NamedAnswerBrand'
          title: Also Named
          type: array
        cited_page_count:
          default: 0
          title: Cited Page Count
          type: integer
        engine:
          enum:
            - perplexity
            - gemini
            - openai
            - google_aio
            - ai_mode
            - copilot
            - claude
          title: Engine
          type: string
        excerpt:
          title: Excerpt
          type: string
        excerpt_highlights:
          items:
            $ref: '#/components/schemas/AnswerHighlightSpan'
          title: Excerpt Highlights
          type: array
        id:
          format: uuid
          title: Id
          type: string
        mentioned:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Mentioned
        own_cited_page_count:
          default: 0
          title: Own Cited Page Count
          type: integer
        prompt:
          title: Prompt
          type: string
        prompt_id:
          format: uuid
          title: Prompt Id
          type: string
        read_at:
          format: date-time
          title: Read At
          type: string
        recommended:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Recommended
        run_class:
          anyOf:
            - type: string
            - type: 'null'
          title: Run Class
        run_number:
          anyOf:
            - type: integer
            - type: 'null'
          title: Run Number
        segment:
          title: Segment
          type: string
        segment_config_version:
          anyOf:
            - type: integer
            - type: 'null'
          title: Segment Config Version
        segment_detail:
          anyOf:
            - $ref: '#/components/schemas/AnswerReadSegment'
            - type: 'null'
        states:
          $ref: '#/components/schemas/AnswerReadStates'
        text_retained:
          default: true
          title: Text Retained
          type: boolean
      required:
        - id
        - prompt_id
        - prompt
        - engine
        - segment
        - read_at
        - mentioned
        - recommended
        - excerpt
        - states
        - segment_detail
        - run_number
        - run_class
        - segment_config_version
        - cited_page_count
        - own_cited_page_count
        - also_named
        - text_retained
        - excerpt_highlights
      title: V1AnswerSummary
      type: object
    EngineVocabulary:
      properties:
        display_name:
          title: Display Name
          type: string
        engine_id:
          title: Engine Id
          type: string
        sort_order:
          title: Sort Order
          type: integer
      required:
        - engine_id
        - display_name
        - sort_order
      title: EngineVocabulary
      type: object
    AnswerFilterOptions:
      description: The brand's prompts and period-wide names and sources, before filtering.
      properties:
        cites:
          items:
            $ref: '#/components/schemas/VocabularyOption'
          title: Cites
          type: array
        names:
          items:
            $ref: '#/components/schemas/NamedAnswerBrand'
          title: Names
          type: array
        prompts:
          items:
            $ref: '#/components/schemas/VocabularyOption'
          title: Prompts
          type: array
      required:
        - prompts
        - names
        - cites
      title: AnswerFilterOptions
      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
    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
    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
    NamedAnswerBrand:
      properties:
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
        name:
          title: Name
          type: string
        tracked:
          default: false
          title: Tracked
          type: boolean
      required:
        - name
        - domain
        - tracked
      title: NamedAnswerBrand
      type: object
    AnswerHighlightSpan:
      description: |-
        One place the answer names the brand or a rival, for the overlay to
        mark: half-open offsets into `answer_text`, counted in Unicode code
        points, with `you` for the brand's own names and `rival` for a rival's.
      properties:
        brand:
          enum:
            - you
            - rival
          title: Brand
          type: string
        end:
          minimum: 0
          title: End
          type: integer
        start:
          minimum: 0
          title: Start
          type: integer
      required:
        - start
        - end
        - brand
      title: AnswerHighlightSpan
      type: object
    AnswerReadSegment:
      properties:
        geo:
          title: Geo
          type: string
        label:
          title: Label
          type: string
        persona_id:
          title: Persona Id
          type: string
      required:
        - label
        - persona_id
        - geo
      title: AnswerReadSegment
      type: object
    AnswerReadStates:
      description: >-
        The four words for how one answer treated the brand (D32, D37).


        The wire shape of `app.scans.scoring.axes.AnswerAxes`, which is where
        the

        reading itself is decided — the report, the roll-ups and this history
        all

        read one answer the same way. `None` is unmeasured and never a zero.
      properties:
        icon_states:
          $ref: '#/components/schemas/IconStates'
          readOnly: true
        mentioned:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Mentioned
        praised:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Praised
        recommended:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Recommended
        understood:
          anyOf:
            - type: number
            - type: 'null'
          title: Understood
      required:
        - mentioned
        - understood
        - recommended
        - praised
        - icon_states
      title: AnswerReadStates
      type: object
    VocabularyOption:
      description: >-
        One value of a served vocabulary, with the one word it reads as.


        A vocabulary the web used to mirror travels with the data it describes:

        the response lists its values in their one order, each with its label,
        and

        a value the web does not know renders as its raw id.
      properties:
        label:
          title: Label
          type: string
        value:
          title: Value
          type: string
      required:
        - value
        - label
      title: VocabularyOption
      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: {}
    IconStates:
      description: Each axis as the icon a row draws for it.
      properties:
        mentioned:
          enum:
            - 'yes'
            - partial
            - 'no'
            - not_measured
          title: Mentioned
          type: string
        praised:
          enum:
            - 'yes'
            - partial
            - 'no'
            - not_measured
          title: Praised
          type: string
        recommended:
          enum:
            - 'yes'
            - partial
            - 'no'
            - not_measured
          title: Recommended
          type: string
        understood:
          enum:
            - 'yes'
            - partial
            - 'no'
            - not_measured
          title: Understood
          type: string
      required:
        - mentioned
        - understood
        - recommended
        - praised
      title: IconStates
      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.