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

> The domains the engines cited over the selected period, daily answers included.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/sources
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}/sources:
    get:
      tags:
        - v1
      summary: Get Sources
      description: >-
        The domains the engines cited over the selected period, daily answers
        included.
      operationId: listSources
      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: 1w
            enum:
              - 1w
              - 4w
              - 12w
              - all
            title: Period
            type: string
        - in: query
          name: owner
          required: false
          schema:
            anyOf:
              - enum:
                  - third_party
                  - competitor
                  - yours
                type: string
              - type: 'null'
            title: Owner
        - in: query
          name: source_type
          required: false
          schema:
            anyOf:
              - enum:
                  - industry_authority
                  - review
                  - regulatory
                  - media
                  - educational
                  - community
                  - consulting
                  - social
                  - vendor
                  - directory
                  - unclassified
                type: string
              - const: corporate
                type: string
              - type: 'null'
            title: Source Type
        - in: query
          name: names_you
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: 'null'
            title: Names You
        - in: query
          name: content_topic
          required: false
          schema:
            anyOf:
              - maxLength: 300
                type: string
              - type: 'null'
            title: Content Topic
        - in: query
          name: q
          required: false
          schema:
            anyOf:
              - maxLength: 200
                type: string
              - type: 'null'
            title: Q
        - in: query
          name: direction
          required: false
          schema:
            anyOf:
              - enum:
                  - asc
                  - desc
                type: string
              - type: 'null'
            title: Direction
        - in: query
          name: with_menus
          required: false
          schema:
            default: false
            title: With Menus
            type: boolean
        - in: query
          name: with_summary
          required: false
          schema:
            default: false
            title: With Summary
            type: boolean
        - in: query
          name: sort
          required: false
          schema:
            default: citations
            enum:
              - domain
              - citations
              - answers
              - change
              - priority
            title: Sort
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Sources'
          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:
    V1Sources:
      properties:
        cards:
          anyOf:
            - $ref: '#/components/schemas/SourcesCards'
            - type: 'null'
        citation_evidence:
          default: complete
          enum:
            - complete
            - partial
            - unavailable
          title: Citation Evidence
          type: string
        limit:
          title: Limit
          type: integer
        menus:
          anyOf:
            - $ref: '#/components/schemas/SourcesMenus'
            - type: 'null'
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        mix:
          items:
            $ref: '#/components/schemas/SourceMixSegment'
          title: Mix
          type: array
        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
        pages_total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Pages Total
        period:
          $ref: '#/components/schemas/V1Period'
        sentence:
          anyOf:
            - type: string
            - type: 'null'
          title: Sentence
        sites_total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sites Total
        sources:
          items:
            $ref: '#/components/schemas/V1Source'
          title: Sources
          type: array
        state:
          anyOf:
            - enum:
                - ready
                - awaiting_first_scan
                - unavailable
              type: string
            - type: 'null'
          title: State
        total:
          title: Total
          type: integer
        unavailable_scans:
          default: 0
          title: Unavailable Scans
          type: integer
        worth_pursuing:
          items:
            $ref: '#/components/schemas/SourceWorthRow'
          title: Worth Pursuing
          type: array
        worth_pursuing_total:
          default: 0
          title: Worth Pursuing Total
          type: integer
      required:
        - meta
        - next_cursor
        - total
        - limit
        - offset
        - period
        - citation_evidence
        - unavailable_scans
        - sources
        - state
        - sentence
        - cards
        - mix
        - sites_total
        - pages_total
        - menus
        - worth_pursuing
        - worth_pursuing_total
      title: V1Sources
      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
    SourcesCards:
      properties:
        answers:
          anyOf:
            - type: integer
            - type: 'null'
          default: 0
          title: Answers
        citations:
          anyOf:
            - type: integer
            - type: 'null'
          default: 0
          title: Citations
        citations_change:
          $ref: '#/components/schemas/SourceCardChange'
        competitors_pages_change:
          $ref: '#/components/schemas/SourceCardChange'
        competitors_pages_change_pts:
          anyOf:
            - type: integer
            - type: 'null'
          title: Competitors Pages Change Pts
        competitors_pages_share_pct:
          anyOf:
            - type: integer
            - type: 'null'
          title: Competitors Pages Share Pct
        sites:
          anyOf:
            - type: integer
            - type: 'null'
          default: 0
          title: Sites
        sites_change:
          $ref: '#/components/schemas/SourceCardChange'
        sites_naming_you:
          anyOf:
            - type: integer
            - type: 'null'
          default: 0
          title: Sites Naming You
        your_pages_change:
          $ref: '#/components/schemas/SourceCardChange'
        your_pages_change_pts:
          anyOf:
            - type: integer
            - type: 'null'
          title: Your Pages Change Pts
        your_pages_share_pct:
          anyOf:
            - type: integer
            - type: 'null'
          title: Your Pages Share Pct
      required:
        - citations
        - answers
        - sites
        - sites_naming_you
        - your_pages_share_pct
        - competitors_pages_share_pct
        - your_pages_change_pts
        - competitors_pages_change_pts
        - citations_change
        - sites_change
        - your_pages_change
        - competitors_pages_change
      title: SourcesCards
      type: object
    SourcesMenus:
      description: >-
        The page's filter menus: the prompt set's four, every source type and
        every

        tracked prompt. None follows the filters, so choosing one hides no
        other.
      properties:
        intents:
          items:
            $ref: '#/components/schemas/PromptFilterOption'
          title: Intents
          type: array
        prompts:
          items:
            $ref: '#/components/schemas/VocabularyOption'
          title: Prompts
          type: array
        segments:
          items:
            $ref: '#/components/schemas/PromptFilterOption'
          title: Segments
          type: array
        source_types:
          items:
            $ref: '#/components/schemas/VocabularyOption'
          title: Source Types
          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
        - source_types
        - prompts
      title: SourcesMenus
      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
    SourceMixSegment:
      properties:
        citations:
          title: Citations
          type: integer
        key:
          title: Key
          type: string
        label:
          title: Label
          type: string
        owner:
          enum:
            - third_party
            - competitor
            - yours
          title: Owner
          type: string
        share_pct:
          title: Share Pct
          type: integer
      required:
        - key
        - label
        - citations
        - share_pct
        - owner
      title: SourceMixSegment
      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
    V1Source:
      properties:
        answers:
          title: Answers
          type: integer
        answers_share_pct:
          anyOf:
            - type: integer
            - type: 'null'
          title: Answers Share Pct
        authority:
          anyOf:
            - type: integer
            - type: 'null'
          title: Authority
        change:
          anyOf:
            - $ref: '#/components/schemas/V1SourceChange'
            - type: 'null'
        citation_share_pct:
          anyOf:
            - type: integer
            - type: 'null'
          title: Citation Share Pct
        citations:
          title: Citations
          type: integer
        citations_naming_rivals:
          title: Citations Naming Rivals
          type: integer
        citations_naming_you:
          deprecated: true
          description: >-
            All citations naming the brand, including unread pages. Use
            read_pages_naming_you for read pages.
          title: Citations Naming You
          type: integer
        domain:
          title: Domain
          type: string
        engines:
          items:
            enum:
              - perplexity
              - gemini
              - openai
              - google_aio
              - ai_mode
              - copilot
              - claude
            type: string
          title: Engines
          type: array
        group:
          enum:
            - own
            - rival
            - review
            - editorial
            - community
            - vendor
            - other
          title: Group
          type: string
        names_you:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Names You
        opportunity_score:
          title: Opportunity Score
          type: number
        owner:
          anyOf:
            - enum:
                - third_party
                - competitor
                - yours
              type: string
            - type: 'null'
          title: Owner
        owner_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Owner Label
        ownership:
          enum:
            - own
            - rival
            - independent
          title: Ownership
          type: string
        priority:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            1-based position among worth-pursuing sites under the selected
            filters; null for sites outside that set. This is a rank, not the
            internal score.
          title: Priority
        priority_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Priority Reason
        prompts:
          title: Prompts
          type: integer
        read_pages_naming_you:
          title: Read Pages Naming You
          type: integer
        source_type:
          anyOf:
            - enum:
                - industry_authority
                - review
                - regulatory
                - media
                - educational
                - community
                - consulting
                - social
                - vendor
                - directory
                - unclassified
              type: string
            - const: corporate
              type: string
            - type: 'null'
          title: Source Type
        source_type_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Type Label
      required:
        - domain
        - group
        - ownership
        - citations
        - citations_naming_you
        - read_pages_naming_you
        - citation_share_pct
        - answers
        - authority
        - opportunity_score
        - priority
        - priority_reason
        - citations_naming_rivals
        - prompts
        - engines
        - owner
        - owner_label
        - source_type
        - source_type_label
        - names_you
        - answers_share_pct
        - change
      title: V1Source
      type: object
    SourceWorthRow:
      properties:
        action_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Action Id
        citations:
          title: Citations
          type: integer
        domain:
          title: Domain
          type: string
        reason:
          title: Reason
          type: string
        source_type:
          anyOf:
            - enum:
                - industry_authority
                - review
                - regulatory
                - media
                - educational
                - community
                - consulting
                - social
                - vendor
                - directory
                - unclassified
              type: string
            - const: corporate
              type: string
          title: Source Type
        source_type_label:
          title: Source Type Label
          type: string
        title:
          title: Title
          type: string
      required:
        - domain
        - source_type
        - source_type_label
        - title
        - reason
        - citations
        - action_id
      title: SourceWorthRow
      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
    SourceCardChange:
      properties:
        current:
          anyOf:
            - type: integer
            - type: 'null'
          title: Current
        delta:
          anyOf:
            - type: number
            - type: 'null'
          title: Delta
        direction:
          default: unmeasured
          enum:
            - up
            - down
            - steady
            - unmeasured
          title: Direction
          type: string
        label:
          default: No comparable previous period
          title: Label
          type: string
        previous:
          anyOf:
            - type: integer
            - type: 'null'
          title: Previous
      required:
        - direction
        - delta
        - previous
        - current
        - label
      title: SourceCardChange
      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
    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
    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: {}
    V1SourceChange:
      properties:
        current:
          title: Current
          type: integer
        delta:
          anyOf:
            - type: number
            - type: 'null'
          title: Delta
        direction:
          enum:
            - up
            - down
            - flat
            - new
          title: Direction
          type: string
        label:
          title: Label
          type: string
        previous:
          anyOf:
            - type: integer
            - type: 'null'
          title: Previous
      required:
        - direction
        - delta
        - previous
        - current
        - label
      title: V1SourceChange
      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.