> ## 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 Focus Cards

> Two served figures for each starred focus.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/focus-cards
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}/focus-cards:
    get:
      tags:
        - v1
      summary: Get Focus Cards
      description: Two served figures for each starred focus.
      operationId: getFocusCards
      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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FocusCards'
          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:
    FocusCards:
      properties:
        items:
          description: One card per starred topic, competitor and market, at most nine.
          items:
            $ref: '#/components/schemas/FocusCard'
          title: Items
          type: array
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
      required:
        - meta
        - items
      title: FocusCards
      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
    FocusCard:
      properties:
        figures:
          description: Two served figures, with measurement states and ranges.
          items:
            $ref: '#/components/schemas/FocusFigure'
          title: Figures
          type: array
        focus:
          $ref: '#/components/schemas/FocusItem'
          description: The star this card measures.
      required:
        - focus
        - figures
      title: FocusCard
      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
    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
    FocusFigure:
      properties:
        figure:
          $ref: '#/components/schemas/Figure'
          description: The served value, range, state and comparison.
        key:
          description: The figure's metric or side of the competitor comparison.
          enum:
            - recommended
            - mentioned
            - your_score
            - competitor_score
          title: Key
          type: string
      required:
        - key
        - figure
      title: FocusFigure
      type: object
    FocusItem:
      properties:
        audience_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Audience UUID; null for All buyers.
          title: Audience Id
        id:
          description: The tracked topic id, competitor key or market profile id.
          title: Id
          type: string
        kind:
          description: topic, competitor or market.
          enum:
            - topic
            - competitor
            - market
          title: Kind
          type: string
        market:
          anyOf:
            - type: string
            - type: 'null'
          description: The topic's or focused market's code.
          title: Market
        name:
          description: The topic's, competitor's or market's name.
          title: Name
          type: string
        tracked:
          description: >-
            False once the tracked topic is archived, its market is retired, or
            the competitor is no longer tracked; the star stays until removed.
          title: Tracked
          type: boolean
      required:
        - kind
        - id
        - name
        - tracked
        - market
        - audience_id
      title: FocusItem
      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
    Figure:
      properties:
        answers:
          title: Answers
          type: integer
        basis:
          default: ai
          description: Evidence used by this figure.
          enum:
            - ai
            - ai_and_web
            - search
          title: Basis
          type: string
        change:
          anyOf:
            - $ref: '#/components/schemas/FigureChange'
            - type: 'null'
        denominator:
          anyOf:
            - type: integer
            - type: 'null'
          title: Denominator
        high:
          anyOf:
            - type: integer
            - type: 'null'
          title: High
        low:
          anyOf:
            - type: integer
            - type: 'null'
          title: Low
        numerator:
          anyOf:
            - type: number
            - type: 'null'
          title: Numerator
        state:
          title: State
          type: string
          x-extensible-enum:
            - measured
            - too_few_answers
            - calibrating
            - first_report
            - not_comparable
            - not_measured
            - pending
            - not_scored
        trend:
          items:
            $ref: '#/components/schemas/FigurePoint'
          title: Trend
          type: array
        value:
          anyOf:
            - type: integer
            - type: 'null'
          title: Value
      required:
        - basis
        - value
        - low
        - high
        - numerator
        - denominator
        - answers
        - state
        - change
        - trend
      title: Figure
      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
    FigureChange:
      properties:
        baseline:
          $ref: '#/components/schemas/ComparisonPeriod'
        cells_unpaired:
          title: Cells Unpaired
          type: integer
        compared_engines:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          description: >-
            The engines `delta` was sized on, when the baseline report asked
            other engines than the current period. The value and the trend still
            include every engine asked. Null when the size is the move the trend
            draws.
          title: Compared Engines
        delta:
          anyOf:
            - type: number
            - type: 'null'
          description: >-
            The move in points: the shown value minus the baseline's, both as
            the trend draws them, or both over `compared_engines` where it names
            engines. Null when the baseline has no value.
          title: Delta
        direction:
          enum:
            - up
            - down
            - steady
          title: Direction
          type: string
        high:
          anyOf:
            - type: number
            - type: 'null'
          description: >-
            The upper end of the paired test's 95% range for the move, in
            points.
          title: High
        low:
          anyOf:
            - type: number
            - type: 'null'
          description: >-
            The lower end of the paired test's 95% range for the move, in
            points.
          title: Low
        real:
          description: >-
            Whether the paired test over the prompt × engine cells both reads
            measured says the figure moved. The state is up or down only when
            this is true and the move has the sign of `delta`; otherwise it is
            steady and carries the signed `delta`.
          title: Real
          type: boolean
        state:
          default: calibrating
          description: >-
            The served comparison state, distinct from whether the figure is
            measured.
          enum:
            - up
            - down
            - steady
            - calibrating
            - first_report
            - not_comparable
          title: State
          type: string
      required:
        - state
        - delta
        - low
        - high
        - real
        - direction
        - baseline
        - cells_unpaired
        - compared_engines
      title: FigureChange
      type: object
    FigurePoint:
      properties:
        answers:
          title: Answers
          type: integer
        at:
          format: date-time
          title: At
          type: string
        break:
          anyOf:
            - $ref: '#/components/schemas/TrendBreak'
            - type: 'null'
          readOnly: true
        breaks:
          items:
            $ref: '#/components/schemas/KeyChange'
          title: Breaks
          type: array
        high:
          anyOf:
            - type: integer
            - type: 'null'
          title: High
        key:
          $ref: '#/components/schemas/ComparabilityKey'
        low:
          anyOf:
            - type: integer
            - type: 'null'
          title: Low
        scan_id:
          format: uuid
          title: Scan Id
          type: string
        state:
          title: State
          type: string
          x-extensible-enum:
            - measured
            - too_few_answers
            - calibrating
            - first_report
            - not_comparable
            - not_measured
            - pending
            - not_scored
        value:
          anyOf:
            - type: integer
            - type: 'null'
          title: Value
      required:
        - scan_id
        - at
        - value
        - low
        - high
        - answers
        - state
        - key
        - breaks
        - break
      title: FigurePoint
      type: object
    ComparisonPeriod:
      properties:
        first_answer_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: First Answer At
        last_answer_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Last Answer At
        reports:
          title: Reports
          type: integer
      required:
        - reports
        - first_answer_at
        - last_answer_at
      title: ComparisonPeriod
      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.