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

> The goal with its revisions, baseline, current figures and target, the focus stars and
the labels the brand is moving away from. Recommended, Mentioned and Understood are read
on the goal's own questions; nothing compares across revisions.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/brands/{brand_id}/strategy
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}/strategy:
    get:
      tags:
        - v1
      summary: Get Strategy
      description: >-
        The goal with its revisions, baseline, current figures and target, the
        focus stars and

        the labels the brand is moving away from. Recommended, Mentioned and
        Understood are read

        on the goal's own questions; nothing compares across revisions.
      operationId: getStrategy
      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/StrategyRead'
          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:
    StrategyRead:
      properties:
        brand_id:
          description: The brand's id.
          format: uuid
          title: Brand Id
          type: string
        focus:
          $ref: '#/components/schemas/Focus'
          description: The stars, at most `limit` of each kind.
        goal:
          anyOf:
            - $ref: '#/components/schemas/Goal'
            - type: 'null'
          description: The current revision of the goal; null before one.
        moving_away_from:
          description: Labels the brand no longer wants to be described by.
          items:
            type: string
          title: Moving Away From
          type: array
        revisions:
          description: >-
            Every revision, newest first, the current one included. Figures
            never compare across two.
          items:
            $ref: '#/components/schemas/GoalRevisionRead'
          title: Revisions
          type: array
      required:
        - brand_id
        - goal
        - revisions
        - focus
        - moving_away_from
      title: StrategyRead
      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
    Focus:
      properties:
        competitors:
          description: Starred competitors, oldest star first.
          items:
            $ref: '#/components/schemas/FocusItem'
          title: Competitors
          type: array
        limit:
          default: 3
          description: The most stars of each kind.
          title: Limit
          type: integer
        markets:
          description: Starred markets, oldest star first.
          items:
            $ref: '#/components/schemas/FocusItem'
          title: Markets
          type: array
        topics:
          description: Starred topics, oldest star first.
          items:
            $ref: '#/components/schemas/FocusItem'
          title: Topics
          type: array
      required:
        - topics
        - competitors
        - markets
        - limit
      title: Focus
      type: object
    Goal:
      properties:
        ended_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the next revision started.
          title: Ended At
        goal:
          description: The goal sentence.
          title: Goal
          type: string
        measure:
          $ref: '#/components/schemas/GoalMeasure'
          description: The current revision's figures.
        prompts:
          description: The questions this revision is measured on.
          title: Prompts
          type: integer
        reason:
          description: What started this revision.
          enum:
            - goal_set
            - goal_changed
            - focus_changed
            - profile_changed
            - domain_changed
          title: Reason
          type: string
        revision:
          description: The revision's number, from 1.
          title: Revision
          type: integer
        started_at:
          description: When this revision started.
          format: date-time
          title: Started At
          type: string
        target:
          anyOf:
            - $ref: '#/components/schemas/GoalTarget'
            - type: 'null'
          description: The Recommended target; null for none.
      required:
        - revision
        - goal
        - target
        - reason
        - started_at
        - ended_at
        - prompts
        - measure
      title: Goal
      type: object
    GoalRevisionRead:
      properties:
        ended_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the next revision started.
          title: Ended At
        goal:
          description: The goal sentence.
          title: Goal
          type: string
        prompts:
          description: The questions this revision is measured on.
          title: Prompts
          type: integer
        reason:
          description: What started this revision.
          enum:
            - goal_set
            - goal_changed
            - focus_changed
            - profile_changed
            - domain_changed
          title: Reason
          type: string
        revision:
          description: The revision's number, from 1.
          title: Revision
          type: integer
        started_at:
          description: When this revision started.
          format: date-time
          title: Started At
          type: string
        target:
          anyOf:
            - $ref: '#/components/schemas/GoalTarget'
            - type: 'null'
          description: The Recommended target; null for none.
      required:
        - revision
        - goal
        - target
        - reason
        - started_at
        - ended_at
        - prompts
      title: GoalRevisionRead
      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
    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
    GoalMeasure:
      properties:
        baseline:
          $ref: '#/components/schemas/GoalBaseline'
          description: Each figure at the baseline report.
        baseline_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the baseline report completed.
          title: Baseline At
        measured_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When the newest report completed.
          title: Measured At
        mentioned:
          $ref: '#/components/schemas/Figure'
          description: Mentioned on the goal's questions, likewise.
        progress:
          description: >-
            measured when a report since the revision's start is compared with
            its baseline, and each figure's change says whether the move is
            real; first_report before the first goal has a second report;
            not_comparable when the revision started after the newest report, or
            a market it is measured on changed setup since.
          enum:
            - measured
            - first_report
            - not_comparable
          title: Progress
          type: string
        recommended:
          $ref: '#/components/schemas/Figure'
          description: >-
            Recommended on the goal's questions; its change is from the baseline
            report and is present only when progress is measured.
        understood:
          $ref: '#/components/schemas/Figure'
          description: Understood on the goal's questions, likewise.
      required:
        - progress
        - baseline_at
        - measured_at
        - recommended
        - mentioned
        - understood
        - baseline
      title: GoalMeasure
      type: object
    GoalTarget:
      properties:
        date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: When it is aimed for; null for none.
          title: Date
        value:
          description: Recommended, in percent of answers.
          maximum: 100
          minimum: 1
          title: Value
          type: integer
      required:
        - value
        - date
      title: GoalTarget
      type: object
    GoalBaseline:
      description: |-
        Each figure at the baseline report, over the prompts and engines both
        reports measured. The current value where the baseline is the newest
        report; null where the figure is not measured or a market changed setup.
      properties:
        mentioned:
          anyOf:
            - type: integer
            - type: 'null'
          description: Mentioned at the baseline.
          title: Mentioned
        recommended:
          anyOf:
            - type: integer
            - type: 'null'
          description: Recommended at the baseline.
          title: Recommended
        understood:
          anyOf:
            - type: integer
            - type: 'null'
          description: Understood at the baseline.
          title: Understood
      required:
        - recommended
        - mentioned
        - understood
      title: GoalBaseline
      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
    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.