> ## 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 Competitor Page

> Read one competitor page’s history, questions and URL-targeted Work.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/competitors/{key}/page
openapi: 3.1.0
info:
  description: >-
    Access to one organization's brands, as the member who created the API key.
    A read-only key reads; a full-access key also starts, edits and runs that
    member's Snapshots on the organization's Snapshot credits. Each key may make
    120 requests a minute. Separate organization service tokens can start
    Snapshots and Full audits and read service audits. Every error is an RFC
    9457 problem (`application/problem+json`) whose `code` names it.
  summary: Read your brands' AI visibility and run Snapshots in Heralded.
  title: Heralded API
  version: '1'
servers:
  - url: https://api.heralded.ai
security: []
paths:
  /v1/brands/{brand_id}/competitors/{key}/page:
    get:
      tags:
        - v1
      summary: Get Competitor Page
      description: Read one competitor page’s history, questions and URL-targeted Work.
      operationId: getCompetitorPage
      parameters:
        - description: The brand’s UUID from listBrands.
          in: path
          name: brand_id
          required: true
          schema:
            description: The brand’s UUID from listBrands.
            format: uuid
            title: Brand Id
            type: string
        - description: The competitor key or page hostname.
          in: path
          name: key
          required: true
          schema:
            description: The competitor key or page hostname.
            maxLength: 300
            minLength: 1
            title: Key
            type: string
        - description: Check country or global. Omit for all.
          in: query
          name: country
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Check country or global. Omit for all.
            title: Country
        - description: Maximum rows (100).
          in: query
          name: limit
          required: false
          schema:
            default: 20
            description: Maximum rows (100).
            maximum: 100
            minimum: 1
            title: Limit
            type: integer
        - description: Prior next_cursor; keep filters and limit.
          in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - maxLength: 4096
                type: string
              - type: 'null'
            description: Prior next_cursor; keep filters and limit.
            title: Cursor
        - description: Completed scan id cutoff.
          in: query
          name: as_of
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            description: Completed scan id cutoff.
            title: As Of
        - description: Rows to skip; prefer cursor paging.
          in: query
          name: offset
          required: false
          schema:
            default: 0
            description: Rows to skip; prefer cursor paging.
            minimum: 0
            title: Offset
            type: integer
        - description: >-
            Country ISO code, europe for pooled Europe, or global for no
            country. Omit for all.
          in: query
          name: market
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Country ISO code, europe for pooled Europe, or global for no
              country. Omit for all.
            title: Market
        - description: >-
            Audience UUID, or all_buyers for topics for all buyers. Omit for
            all.
          in: query
          name: audience
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - const: all_buyers
                type: string
              - type: 'null'
            description: >-
              Audience UUID, or all_buyers for topics for all buyers. Omit for
              all.
            title: Audience
        - description: Answering AI engine.
          in: query
          name: engine
          required: false
          schema:
            anyOf:
              - enum:
                  - perplexity
                  - gemini
                  - openai
                  - google_aio
                  - ai_mode
                  - copilot
                  - claude
                type: string
              - type: 'null'
            description: Answering AI engine.
            title: Engine
        - description: Question type.
          in: query
          name: type
          required: false
          schema:
            anyOf:
              - enum:
                  - organic
                  - brand_specific
                  - competitor_comparison
                type: string
              - type: 'null'
            description: Question type.
            title: Type
        - description: Question intent.
          in: query
          name: intent
          required: false
          schema:
            anyOf:
              - enum:
                  - educational
                  - problem
                  - comparison
                  - transactional
                type: string
              - type: 'null'
            description: Question intent.
            title: Intent
        - description: Tracked topic UUID.
          in: query
          name: topic
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            description: Tracked topic UUID.
            title: Topic
        - description: Question id from list_prompts.
          in: query
          name: prompt
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            description: Question id from list_prompts.
            title: Prompt
        - description: Weekly-report period.
          in: query
          name: period
          required: false
          schema:
            default: 1w
            description: Weekly-report period.
            enum:
              - 1w
              - 4w
              - 12w
              - all
            title: Period
            type: string
        - description: The competitor page URL to read.
          in: query
          name: page_url
          required: true
          schema:
            description: The competitor page URL to read.
            maxLength: 4096
            title: Page Url
            type: string
        - description: Page this section with limit and offset; omit for both previews.
          in: query
          name: section
          required: false
          schema:
            anyOf:
              - enum:
                  - questions
                  - work
                type: string
              - type: 'null'
            description: Page this section with limit and offset; omit for both previews.
            title: Section
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1RivalPageRead'
          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: https://docs.heralded.ai/errors-and-limits#invalid_cursor
              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: https://docs.heralded.ai/errors-and-limits#invalid_token
              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: https://docs.heralded.ai/errors-and-limits#not_found
              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: https://docs.heralded.ai/errors-and-limits#workspace_archived
              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: https://docs.heralded.ai/errors-and-limits#invalid_request
              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: https://docs.heralded.ai/errors-and-limits#rate_limited
              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:
    V1RivalPageRead:
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        rival:
          $ref: '#/components/schemas/RivalPagePane'
          description: >-
            The selected competitor page and its bounded citing questions and
            URL-specific work.
      required:
        - meta
        - rival
      title: V1RivalPageRead
      type: object
    Problem:
      description: An RFC 9457 problem linking its code to human-readable documentation.
      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:
          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:
          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:
          title: Type
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - instance
        - rate_limit
      title: RateLimitProblem
      type: object
    Meta:
      properties:
        data_as_of:
          anyOf:
            - $ref: '#/components/schemas/DataAsOf'
            - type: 'null'
        last_attempt_failed:
          default: false
          description: The newest attempt failed; the last good result is displayed.
          title: Last Attempt Failed
          type: boolean
        partial:
          default: false
          description: The displayed response includes a partial report.
          title: Partial
          type: boolean
        query:
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          title: Query
          type: object
        surfaces:
          additionalProperties:
            $ref: '#/components/schemas/SurfaceFreshness'
          description: >-
            Freshness by Command Center surface key. Each entry describes its
            own displayed result, including results without a scan.
          title: Surfaces
          type: object
        updating:
          default: false
          description: A newer result is being produced or is not yet displayed.
          title: Updating
          type: boolean
      required:
        - query
        - data_as_of
        - partial
        - updating
        - last_attempt_failed
        - surfaces
      title: Meta
      type: object
    RivalPagePane:
      properties:
        actions:
          items:
            $ref: '#/components/schemas/PaneAction'
          title: Actions
          type: array
        actions_total:
          default: 0
          description: Every live action about this subject, before the list is cut.
          title: Actions Total
          type: integer
        answers_link:
          anyOf:
            - $ref: '#/components/schemas/AnswersLink'
            - type: 'null'
        brand_key:
          title: Brand Key
          type: string
        brand_name:
          title: Brand Name
          type: string
        citation_evidence:
          default: complete
          enum:
            - complete
            - partial
            - unavailable
          title: Citation Evidence
          type: string
        content_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Type
        engine_ids:
          items:
            type: string
          title: Engine Ids
          type: array
        engine_vocabulary:
          items:
            $ref: '#/components/schemas/EngineVocabulary'
          title: Engine Vocabulary
          type: array
        first_cited_at:
          anyOf:
            - type: string
            - type: 'null'
          title: First Cited At
        headline:
          title: Headline
          type: string
        measurement:
          description: >-
            How the page was measured. New measurement values may be added
            within v1.
          title: Measurement
          type: string
          x-extensible-enum:
            - measured
            - daily_only
            - unavailable
        next_step:
          anyOf:
            - $ref: '#/components/schemas/PaneAction'
            - type: 'null'
          description: >-
            The action `next_step_action_id` names, in the same shape as
            `actions`.
        next_step_action_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            The highest-priority live action that awaits a member and whose verb
            the reader may press; null when there is none.
          title: Next Step Action Id
        prompt_count:
          description: Prompts represented by this row under the selected filters.
          title: Prompt Count
          type: integer
        prompts:
          items:
            $ref: '#/components/schemas/PanePrompt'
          title: Prompts
          type: array
        prompts_limit:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            Maximum citing questions returned in this page; null for the
            complete selection.
          title: Prompts Limit
        prompts_offset:
          default: 0
          description: Citing questions skipped before this page.
          title: Prompts Offset
          type: integer
        question_trend:
          anyOf:
            - $ref: '#/components/schemas/MetricSeries'
            - type: 'null'
          description: >-
            Weekly counts of distinct tracked questions citing this page under
            the selected filters; null without a preview read.
        questions_delta:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            Change in distinct citing questions against the preceding comparable
            period; null with missing or incomparable citation coverage.
          title: Questions Delta
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        total_prompt_count:
          description: All prompts for this competitor before paging.
          title: Total Prompt Count
          type: integer
        unavailable_scans:
          default: 0
          title: Unavailable Scans
          type: integer
        url:
          title: Url
          type: string
        why_it_works:
          anyOf:
            - type: string
            - type: 'null'
          title: Why It Works
        window:
          anyOf:
            - $ref: '#/components/schemas/WindowDescriptor'
            - type: 'null'
      required:
        - question_trend
        - questions_delta
        - answers_link
        - engine_vocabulary
        - window
        - url
        - title
        - brand_key
        - brand_name
        - content_type
        - headline
        - measurement
        - citation_evidence
        - unavailable_scans
        - prompt_count
        - total_prompt_count
        - engine_ids
        - first_cited_at
        - why_it_works
        - prompts
        - prompts_limit
        - prompts_offset
        - actions
        - actions_total
        - next_step_action_id
        - next_step
      title: RivalPagePane
      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
    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: {}
    SurfaceFreshness:
      properties:
        as_of:
          anyOf:
            - $ref: '#/components/schemas/SurfaceAsOf'
            - type: 'null'
          description: The result displayed here.
        last_attempt_failed:
          default: false
          description: The newest attempt failed; any displayed result is retained.
          title: Last Attempt Failed
          type: boolean
        partial:
          default: false
          description: The displayed report is partial.
          title: Partial
          type: boolean
        updating:
          default: false
          description: A newer attempt exists whose result is not yet displayed.
          title: Updating
          type: boolean
      required:
        - as_of
        - partial
        - updating
        - last_attempt_failed
      title: SurfaceFreshness
      type: object
    PaneAction:
      description: The response the rival already has queued, as the pane shows it.
      properties:
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
        expected_impact_pts:
          anyOf:
            - type: integer
            - type: 'null'
          description: Always null.
          title: Expected Impact Pts
        id:
          title: Id
          type: string
        impact_scale:
          anyOf:
            - type: string
            - type: 'null'
          title: Impact Scale
        status:
          title: Status
          type: string
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
      required:
        - id
        - title
        - detail
        - status
        - expected_impact_pts
        - impact_scale
      title: PaneAction
      type: object
    AnswersLink:
      properties:
        href:
          title: Href
          type: string
      required:
        - href
      title: AnswersLink
      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
    PanePrompt:
      properties:
        answer_read_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Answer Read Id
        intent:
          anyOf:
            - type: string
            - type: 'null'
          title: Intent
        prompt_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt Type
        prompt_uid:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt Uid
        query_id:
          title: Query Id
          type: string
        search_volume:
          anyOf:
            - type: integer
            - type: 'null'
          title: Search Volume
        text:
          title: Text
          type: string
        winner_brand_keys:
          items:
            type: string
          title: Winner Brand Keys
          type: array
      required:
        - query_id
        - prompt_uid
        - text
        - intent
        - prompt_type
        - search_volume
        - winner_brand_keys
        - answer_read_id
      title: PanePrompt
      type: object
    MetricSeries:
      properties:
        introduced_at_run:
          anyOf:
            - type: integer
            - type: 'null'
          title: Introduced At Run
        metric:
          title: Metric
          type: string
        points:
          items:
            $ref: '#/components/schemas/SeriesPoint'
          title: Points
          type: array
      required:
        - metric
        - introduced_at_run
        - points
      title: MetricSeries
      type: object
    WindowDescriptor:
      properties:
        choice:
          enum:
            - latest
            - 4w
            - 12w
          title: Choice
          type: string
        first_read_at:
          anyOf:
            - type: string
            - type: 'null'
          title: First Read At
        last_read_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Read At
        reads:
          title: Reads
          type: integer
      required:
        - choice
        - reads
        - first_read_at
        - last_read_at
      title: WindowDescriptor
      type: object
    SurfaceAsOf:
      properties:
        at:
          description: When the displayed result was measured.
          format: date-time
          title: At
          type: string
        scan_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: The result's scan, null for a timestamp-only result.
          title: Scan Id
      required:
        - scan_id
        - at
      title: SurfaceAsOf
      type: object
    SeriesPoint:
      properties:
        break:
          anyOf:
            - $ref: '#/components/schemas/TrendBreak'
            - type: 'null'
          readOnly: true
        breaks:
          default: []
          items:
            $ref: '#/components/schemas/KeyChange'
          title: Breaks
          type: array
        completed_at:
          title: Completed At
          type: string
        degraded:
          default: false
          title: Degraded
          type: boolean
        key:
          anyOf:
            - $ref: '#/components/schemas/ComparabilityKey'
            - type: 'null'
        measured_domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Measured Domain
        prompts_changed:
          default: false
          title: Prompts Changed
          type: boolean
        run_number:
          title: Run Number
          type: integer
        value:
          anyOf:
            - type: number
            - type: integer
            - type: 'null'
          title: Value
      required:
        - run_number
        - completed_at
        - value
        - degraded
        - measured_domain
        - key
        - breaks
        - prompts_changed
        - break
      title: SeriesPoint
      type: object
    TrendBreak:
      properties:
        at:
          description: Date of the new baseline.
          format: date
          title: At
          type: string
        comparable:
          description: Whether the changed instrument still permits comparison.
          title: Comparable
          type: boolean
        engines_added:
          description: Engines added at this baseline.
          items:
            type: string
          title: Engines Added
          type: array
        engines_removed:
          description: Engines removed at this baseline.
          items:
            type: string
          title: Engines Removed
          type: array
        parts:
          description: Instrument parts that changed.
          items:
            type: string
            x-extensible-enum:
              - engines
              - language
              - market
              - score_version
              - answer_pack_version
              - understood_measure
              - sells_to
              - shopping_pack_version
          title: Parts
          type: array
      required:
        - at
        - parts
        - engines_added
        - engines_removed
        - comparable
      title: TrendBreak
      type: object
    KeyChange:
      description: One part of the instrument that changed between two reads.
      properties:
        added:
          default: []
          items:
            type: string
          title: Added
          type: array
        part:
          title: Part
          type: string
          x-extensible-enum:
            - engines
            - language
            - market
            - score_version
            - answer_pack_version
            - understood_measure
            - sells_to
            - shopping_pack_version
        removed:
          default: []
          items:
            type: string
          title: Removed
          type: array
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
      required:
        - part
        - added
        - removed
        - value
      title: KeyChange
      type: object
    ComparabilityKey:
      description: |-
        The instrument one read was taken with. A part that cannot be told is
        None, and a None part never breaks a series: a run whose answers the
        retention sweep took no longer says which engines it asked.
      properties:
        answer_pack_version:
          anyOf:
            - type: integer
            - type: 'null'
          title: Answer Pack Version
        ecommerce:
          anyOf:
            - type: boolean
            - type: 'null'
          description: >-
            Whether the run measured the brand as ecommerce. A change never
            breaks a series; null where unknown.
          title: Ecommerce
        engines:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Engines
        keyword_set_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Keyword Set Hash
        markets:
          additionalProperties:
            type: string
          default: {}
          title: Markets
          type: object
        passes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Passes
        score_version:
          title: Score Version
          type: string
        sells_to:
          anyOf:
            - enum:
                - businesses
                - consumers
              type: string
            - type: 'null'
          description: >-
            Who the run measured the brand as selling to. A change starts a new
            series; null where unknown.
          title: Sells To
        shopping_pack_version:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            The version of the reading that judged the report's product cards.
            Only product card figures compare it; null where the report read no
            product cards.
          title: Shopping Pack Version
        sides:
          anyOf:
            - items:
                enum:
                  - ai
                  - search
                type: string
              type: array
            - type: 'null'
          title: Sides
        understood_measure:
          anyOf:
            - enum:
                - statements
                - parts
              type: string
            - type: 'null'
          description: >-
            How the report read Understood: each profile statement whole, or
            part by part. Only Understood's trend and change compare it; null
            where unknown.
          title: Understood Measure
      required:
        - engines
        - markets
        - score_version
        - answer_pack_version
        - passes
        - sides
        - keyword_set_hash
        - understood_measure
        - sells_to
        - ecommerce
        - shopping_pack_version
      title: ComparabilityKey
      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.