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

> The tracked prompts and how each engine's latest answer treated the brand.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/prompts
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}/prompts:
    get:
      tags:
        - v1
      summary: Get Prompts
      description: >-
        The tracked prompts and how each engine's latest answer treated the
        brand.
      operationId: listPrompts
      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
        - in: query
          name: period
          required: false
          schema:
            default: 4w
            enum:
              - 1w
              - 4w
              - 12w
              - all
            title: Period
            type: string
        - in: query
          name: prompt_type
          required: false
          schema:
            anyOf:
              - maxLength: 100
                type: string
              - type: 'null'
            title: Prompt Type
        - in: query
          name: topic_id
          required: false
          schema:
            anyOf:
              - maxLength: 100
                type: string
              - type: 'null'
            title: Topic Id
        - in: query
          name: sort
          required: false
          schema:
            anyOf:
              - enum:
                  - volume
                  - change
                  - presence
                  - name
                  - prompt
                  - score
                  - trend
                type: string
              - type: 'null'
            title: Sort
        - in: query
          name: direction
          required: false
          schema:
            anyOf:
              - enum:
                  - asc
                  - desc
                type: string
              - type: 'null'
            title: Direction
        - in: query
          name: you
          required: false
          schema:
            anyOf:
              - enum:
                  - named
                  - not_named
                type: string
              - type: 'null'
            title: You
        - in: query
          name: search
          required: false
          schema:
            anyOf:
              - maxLength: 1000
                type: string
              - type: 'null'
            title: Search
        - in: query
          name: archived
          required: false
          schema:
            default: false
            title: Archived
            type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Prompts'
          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:
    V1Prompts:
      examples:
        - limit: 20
          offset: 0
          prompts:
            - engines:
                - answer_id: 5d2e8c1f-7a3b-4c6d-9e0f-1a2b3c4d5e6f
                  engine: openai
                  state: recommended
                  state_label: Recommended
              id: 0b8e5f7a-2c4d-4e6f-8a1b-3c5d7e9f1a2b
              intent: comparison
              segment: Agencies
              status: active
              text: best crm for agencies
              topic: CRM
          total: 1
      properties:
        active_total:
          default: 0
          title: Active Total
          type: integer
        archived_total:
          default: 0
          title: Archived Total
          type: integer
        engine_vocabulary:
          items:
            $ref: '#/components/schemas/EngineVocabulary'
          title: Engine Vocabulary
          type: array
        filters:
          $ref: '#/components/schemas/PromptFilters'
        has_more:
          default: false
          title: Has More
          type: boolean
        limit:
          title: Limit
          type: integer
        measurement:
          anyOf:
            - $ref: '#/components/schemas/KeywordMeasurement'
            - type: 'null'
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        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'
        prompt_text_max_len:
          default: 200
          title: Prompt Text Max Len
          type: integer
        prompts:
          items:
            $ref: '#/components/schemas/V1Prompt'
          title: Prompts
          type: array
        sort:
          default: volume
          enum:
            - volume
            - change
            - presence
            - name
            - prompt
            - score
            - trend
          title: Sort
          type: string
        total:
          title: Total
          type: integer
        tracked_total:
          default: 0
          title: Tracked Total
          type: integer
      required:
        - meta
        - next_cursor
        - total
        - limit
        - offset
        - measurement
        - prompts
        - engine_vocabulary
        - period
        - filters
        - tracked_total
        - active_total
        - archived_total
        - has_more
        - sort
        - prompt_text_max_len
      title: V1Prompts
      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
    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
    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
    KeywordMeasurement:
      properties:
        country:
          anyOf:
            - type: string
            - type: 'null'
          description: Requested country; null means Global.
          title: Country
        coverage:
          $ref: '#/components/schemas/KeywordCoverage'
          description: >-
            Current catalog availability, not a historical snapshot. Unknown
            means no catalog is available.
        language:
          description: Product language code, independent of vendor aliases.
          title: Language
          type: string
        measured_country:
          description: Country actually targeted; Global uses US.
          title: Measured Country
          type: string
      required:
        - country
        - measured_country
        - language
        - coverage
      title: KeywordMeasurement
      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
    V1Prompt:
      properties:
        cells:
          items:
            $ref: '#/components/schemas/PromptCell'
          title: Cells
          type: array
        change:
          anyOf:
            - $ref: '#/components/schemas/PromptChange'
            - type: 'null'
        engines:
          items:
            $ref: '#/components/schemas/V1PromptEngine'
          title: Engines
          type: array
        id:
          format: uuid
          title: Id
          type: string
        intent:
          anyOf:
            - type: string
            - type: 'null'
          title: Intent
        intent_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Intent Label
        marks:
          items:
            $ref: '#/components/schemas/ScoreMark'
          title: Marks
          type: array
        measurement:
          anyOf:
            - $ref: '#/components/schemas/KeywordMeasurement'
            - type: 'null'
        prompt_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt Type
        score:
          anyOf:
            - $ref: '#/components/schemas/ScoreMark'
            - type: 'null'
        search_volume:
          anyOf:
            - type: integer
            - type: 'null'
          title: Search Volume
        segment:
          title: Segment
          type: string
        segment_detail:
          anyOf:
            - $ref: '#/components/schemas/PromptSegment'
            - type: 'null'
        status:
          enum:
            - active
            - paused
            - archived
          title: Status
          type: string
        status_note:
          anyOf:
            - type: string
            - type: 'null'
          title: Status Note
        status_since:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Status Since
        text:
          title: Text
          type: string
        topic:
          anyOf:
            - type: string
            - type: 'null'
          title: Topic
        topic_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Topic Id
        trend:
          anyOf:
            - $ref: '#/components/schemas/PromptTrend'
            - type: 'null'
        type_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Type Label
      required:
        - measurement
        - id
        - text
        - status
        - topic
        - intent
        - segment
        - engines
        - status_since
        - status_note
        - prompt_type
        - type_label
        - intent_label
        - topic_id
        - segment_detail
        - search_volume
        - change
        - score
        - trend
        - marks
        - cells
      title: V1Prompt
      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
    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
    KeywordCoverage:
      properties:
        keyword_research:
          description: Availability of discovery and difficulty.
          enum:
            - available
            - unavailable
            - unknown
          title: Keyword Research
          type: string
        search_volume:
          description: Availability of monthly keyword search volume.
          enum:
            - available
            - unavailable
            - unknown
          title: Search Volume
          type: string
      required:
        - keyword_research
        - search_volume
      title: KeywordCoverage
      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: {}
    PromptCell:
      properties:
        answer_read_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Answer Read Id
        days:
          anyOf:
            - type: string
            - type: 'null'
          title: Days
        display_name:
          title: Display Name
          type: string
        engine_id:
          title: Engine Id
          type: string
        state:
          enum:
            - leading
            - recommended
            - mentioned
            - weak
            - absent
            - unmeasured
          title: State
          type: string
        state_label:
          readOnly: true
          title: State Label
          type: string
        winner:
          default: unmeasured
          enum:
            - you
            - rival
            - none
            - unmeasured
          title: Winner
          type: string
      required:
        - engine_id
        - display_name
        - state
        - answer_read_id
        - winner
        - days
        - state_label
      title: PromptCell
      type: object
    PromptChange:
      description: 'The change column, in words (D31: a row never carries a spark).'
      properties:
        direction:
          enum:
            - up
            - down
            - flat
            - new
          title: Direction
          type: string
        engines:
          items:
            type: string
          title: Engines
          type: array
        label:
          title: Label
          type: string
      required:
        - direction
        - label
        - engines
      title: PromptChange
      type: object
    V1PromptEngine:
      properties:
        answer_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Answer Id
        engine:
          enum:
            - perplexity
            - gemini
            - openai
            - google_aio
            - ai_mode
            - copilot
            - claude
          title: Engine
          type: string
        reading:
          default: false
          title: Reading
          type: boolean
        state:
          enum:
            - leading
            - recommended
            - mentioned
            - weak
            - absent
            - unmeasured
          title: State
          type: string
        state_label:
          readOnly: true
          title: State Label
          type: string
      required:
        - engine
        - state
        - answer_id
        - reading
        - state_label
      title: V1PromptEngine
      type: object
    ScoreMark:
      description: >-
        A score or figure from the figures read, with the band it is coloured

        by (#4259).


        `key` is the engine or the figure measured. `band` is the Heralded
        Score's

        band for the value, so a mark and a score read on one scale, and

        "Not measured" where no value is served, which includes a group under
        the

        minimum of answers. On a score, `answers` counts every answer the period

        read under the filters, including those a figure's own denominator
        leaves

        out.
      properties:
        answer_read_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Answer Read Id
        answers:
          title: Answers
          type: integer
        band:
          title: Band
          type: string
        key:
          title: Key
          type: string
        label:
          title: Label
          type: string
        state:
          enum:
            - measured
            - too_few_answers
            - calibrating
            - first_report
            - not_comparable
            - not_measured
          title: State
          type: string
        tooltip:
          anyOf:
            - type: string
            - type: 'null'
          title: Tooltip
        value:
          anyOf:
            - type: integer
            - type: 'null'
          title: Value
      required:
        - key
        - label
        - value
        - state
        - band
        - answers
        - tooltip
        - answer_read_id
      title: ScoreMark
      type: object
    PromptSegment:
      properties:
        geo:
          title: Geo
          type: string
        label:
          title: Label
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        persona_id:
          title: Persona Id
          type: string
      required:
        - label
        - persona_id
        - geo
        - name
      title: PromptSegment
      type: object
    PromptTrend:
      description: A score's change, as the Trend column and the pane state it.
      properties:
        delta:
          anyOf:
            - type: integer
            - type: 'null'
          title: Delta
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
        state:
          enum:
            - up
            - down
            - steady
            - not_comparable
            - calibrating
            - new
            - none
          title: State
          type: string
      required:
        - state
        - delta
        - label
      title: PromptTrend
      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.