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

> Published measurements under one market and optional filters. No credential required.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/leaderboards
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/leaderboards:
    get:
      tags:
        - v1
      summary: Get Leaderboards
      description: >-
        Published measurements under one market and optional filters. No
        credential required.
      operationId: getLeaderboards
      parameters:
        - description: An industry slug from the facets.
          in: query
          name: industry
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: An industry slug from the facets.
            title: Industry
        - description: >-
            The market asked from: an ISO 3166-1 alpha-2 country, or `europe`
            for the board pooling the seven European countries. Omit it for
            Global.
          in: query
          name: country
          required: false
          schema:
            anyOf:
              - pattern: ^(?:[A-Z]{2}|europe)$
                type: string
              - type: 'null'
            description: >-
              The market asked from: an ISO 3166-1 alpha-2 country, or `europe`
              for the board pooling the seven European countries. Omit it for
              Global.
            title: Country
        - description: Publication month as YYYY-MM; omit for the latest.
          in: query
          name: month
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Publication month as YYYY-MM; omit for the latest.
            title: Month
        - description: >-
            AI and All use Heralded Scores and comparable history. Search keeps
            Google shares without a score or rank, and is empty where Google was
            not measured.
          in: query
          name: side
          required: false
          schema:
            default: all
            description: >-
              AI and All use Heralded Scores and comparable history. Search
              keeps Google shares without a score or rank, and is empty where
              Google was not measured.
            enum:
              - all
              - ai
              - search
            title: Side
            type: string
        - description: Brand origin as an ISO country code.
          in: query
          name: origin_country
          required: false
          schema:
            anyOf:
              - pattern: ^[A-Z]{2}$
                type: string
              - type: 'null'
            description: Brand origin as an ISO country code.
            title: Origin Country
        - description: Order by scores or podium places.
          in: query
          name: order
          required: false
          schema:
            default: default
            description: Order by scores or podium places.
            enum:
              - default
              - medals
            title: Order
            type: string
        - description: Brand-name substring search.
          in: query
          name: q
          required: false
          schema:
            anyOf:
              - maxLength: 200
                type: string
              - type: 'null'
            description: Brand-name substring search.
            title: Q
        - description: Filter brands by their audience.
          in: query
          name: audience
          required: false
          schema:
            anyOf:
              - enum:
                  - b2b
                  - b2c
                  - both
                type: string
              - type: 'null'
            description: Filter brands by their audience.
            title: Audience
        - description: Filter by source category.
          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: brand_site
                type: string
              - type: 'null'
            description: Filter by source category.
            title: Source Type
        - description: Include brand sites in the source ranking and its total.
          in: query
          name: include_brand_sites
          required: false
          schema:
            default: false
            description: Include brand sites in the source ranking and its total.
            title: Include Brand Sites
            type: boolean
        - description: Maximum rows to return, up to 100.
          in: query
          name: limit
          required: false
          schema:
            default: 10
            description: Maximum rows to return, up to 100.
            maximum: 100
            minimum: 1
            title: Limit
            type: integer
        - description: Rows to skip in brands.
          in: query
          name: brands_offset
          required: false
          schema:
            default: 0
            description: Rows to skip in brands.
            minimum: 0
            title: Brands Offset
            type: integer
        - description: Sources to skip.
          in: query
          name: sources_offset
          required: false
          schema:
            default: 0
            description: Sources to skip.
            minimum: 0
            title: Sources Offset
            type: integer
        - description: Rows to skip in source pages.
          in: query
          name: source_pages_offset
          required: false
          schema:
            default: 0
            description: Rows to skip in source pages.
            minimum: 0
            title: Source Pages Offset
            type: integer
        - description: Rows to skip in engines.
          in: query
          name: engines_offset
          required: false
          schema:
            default: 0
            description: Rows to skip in engines.
            minimum: 0
            title: Engines Offset
            type: integer
        - description: Related prompts to skip.
          in: query
          name: prompts_offset
          required: false
          schema:
            default: 0
            description: Related prompts to skip.
            minimum: 0
            title: Prompts Offset
            type: integer
        - description: Rows to skip in movers.
          in: query
          name: movers_offset
          required: false
          schema:
            default: 0
            description: Rows to skip in movers.
            minimum: 0
            title: Movers Offset
            type: integer
        - description: Rows to skip in dropouts.
          in: query
          name: dropouts_offset
          required: false
          schema:
            default: 0
            description: Rows to skip in dropouts.
            minimum: 0
            title: Dropouts Offset
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Leaderboard'
          description: Successful Response
        '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 published leaderboard contains this brand or source.
        '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 greater than or equal to 1
                    type: greater_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: Invalid filters or pagination.
        '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: 60
                  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 anonymous IP or site-key bucket is exhausted.
          headers:
            Retry-After:
              schema:
                example: 60
                type: integer
components:
  schemas:
    Leaderboard:
      properties:
        brands:
          $ref: '#/components/schemas/BrandsRead'
        dropouts:
          $ref: '#/components/schemas/RankChangesRead'
        engines:
          $ref: '#/components/schemas/EnginesRead'
        filters:
          $ref: '#/components/schemas/LeaderboardFilters'
        leader:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          title: Leader
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        month:
          anyOf:
            - type: string
            - type: 'null'
          title: Month
        months:
          items:
            type: string
          title: Months
          type: array
        movers:
          $ref: '#/components/schemas/Movers'
        origin_counts:
          additionalProperties:
            type: integer
          title: Origin Counts
          type: object
        population:
          anyOf:
            - type: integer
            - type: 'null'
          title: Population
        previous_month:
          anyOf:
            - type: string
            - type: 'null'
          title: Previous Month
        prompts:
          $ref: '#/components/schemas/PromptsRead'
        ranked:
          title: Ranked
          type: boolean
        sources:
          $ref: '#/components/schemas/SourcesRead'
      required:
        - meta
        - filters
        - month
        - ranked
        - population
        - leader
        - months
        - brands
        - origin_counts
        - sources
        - engines
        - prompts
        - previous_month
        - movers
        - dropouts
      title: Leaderboard
      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
    BrandsRead:
      properties:
        limit:
          title: Limit
          type: integer
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Pass as cursor with the same query to read the next page; null at
            the end.
          title: Next Cursor
        offset:
          title: Offset
          type: integer
        rows:
          items:
            $ref: '#/components/schemas/BrandRow'
          title: Rows
          type: array
        total:
          title: Total
          type: integer
      required:
        - meta
        - next_cursor
        - total
        - limit
        - offset
        - rows
      title: BrandsRead
      type: object
    RankChangesRead:
      properties:
        limit:
          title: Limit
          type: integer
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Pass as cursor with the same query to read the next page; null at
            the end.
          title: Next Cursor
        offset:
          title: Offset
          type: integer
        rows:
          items:
            $ref: '#/components/schemas/RankChangeRow'
          title: Rows
          type: array
        total:
          title: Total
          type: integer
      required:
        - meta
        - next_cursor
        - total
        - limit
        - offset
        - rows
      title: RankChangesRead
      type: object
    EnginesRead:
      properties:
        limit:
          title: Limit
          type: integer
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Pass as cursor with the same query to read the next page; null at
            the end.
          title: Next Cursor
        offset:
          title: Offset
          type: integer
        rows:
          items:
            $ref: '#/components/schemas/LeaderboardEngineRow'
          title: Rows
          type: array
        total:
          title: Total
          type: integer
      required:
        - meta
        - next_cursor
        - total
        - limit
        - offset
        - rows
      title: EnginesRead
      type: object
    LeaderboardFilters:
      properties:
        audience:
          anyOf:
            - enum:
                - b2b
                - b2c
                - both
              type: string
            - type: 'null'
          description: Filter brands by their audience.
          title: Audience
        country:
          anyOf:
            - pattern: ^(?:[A-Z]{2}|europe)$
              type: string
            - type: 'null'
          description: >-
            The market asked from: an ISO 3166-1 alpha-2 country, or `europe`
            for the board pooling the seven European countries. Omit it for
            Global.
          title: Country
        include_brand_sites:
          default: false
          description: Include brand sites in the source ranking and its total.
          title: Include Brand Sites
          type: boolean
        industry:
          anyOf:
            - type: string
            - type: 'null'
          description: An industry slug from the facets.
          title: Industry
        month:
          anyOf:
            - type: string
            - type: 'null'
          description: Publication month as YYYY-MM; omit for the latest.
          title: Month
        order:
          default: default
          description: Order by scores or podium places.
          enum:
            - default
            - medals
          title: Order
          type: string
        origin_country:
          anyOf:
            - pattern: ^[A-Z]{2}$
              type: string
            - type: 'null'
          description: Brand origin as an ISO country code.
          title: Origin Country
        q:
          anyOf:
            - maxLength: 200
              type: string
            - type: 'null'
          description: Brand-name substring search.
          title: Q
        side:
          default: all
          description: >-
            AI and All use Heralded Scores and comparable history. Search keeps
            Google shares without a score or rank, and is empty where Google was
            not measured.
          enum:
            - all
            - ai
            - search
          title: Side
          type: string
        source_type:
          anyOf:
            - enum:
                - industry_authority
                - review
                - regulatory
                - media
                - educational
                - community
                - consulting
                - social
                - vendor
                - directory
                - unclassified
              type: string
            - const: brand_site
              type: string
            - type: 'null'
          description: Filter by source category.
          title: Source Type
      required:
        - industry
        - country
        - month
        - side
        - origin_country
        - order
        - q
        - audience
        - source_type
        - include_brand_sites
      title: LeaderboardFilters
      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
    Movers:
      properties:
        fallers:
          $ref: '#/components/schemas/RankChangesRead'
        risers:
          $ref: '#/components/schemas/RankChangesRead'
      required:
        - risers
        - fallers
      title: Movers
      type: object
    PromptsRead:
      properties:
        limit:
          title: Limit
          type: integer
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Pass as cursor with the same query to read the next page; null at
            the end.
          title: Next Cursor
        offset:
          title: Offset
          type: integer
        rows:
          items:
            $ref: '#/components/schemas/LeaderboardPromptRow'
          title: Rows
          type: array
        total:
          title: Total
          type: integer
      required:
        - meta
        - next_cursor
        - total
        - limit
        - offset
        - rows
      title: PromptsRead
      type: object
    SourcesRead:
      properties:
        limit:
          title: Limit
          type: integer
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Pass as cursor with the same query to read the next page; null at
            the end.
          title: Next Cursor
        offset:
          title: Offset
          type: integer
        rows:
          items:
            $ref: '#/components/schemas/SourceRow'
          title: Rows
          type: array
        state:
          enum:
            - complete
            - partial
            - unavailable
          title: State
          type: string
        total:
          title: Total
          type: integer
        withheld:
          description: Ranks present in the module whose rows are withheld.
          items:
            type: integer
          title: Withheld
          type: array
      required:
        - meta
        - next_cursor
        - total
        - limit
        - offset
        - withheld
        - rows
        - state
      title: SourcesRead
      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
    BrandRow:
      properties:
        audience:
          anyOf:
            - type: string
            - type: 'null'
          title: Audience
        brand_id:
          format: uuid
          title: Brand Id
          type: string
        change_state:
          enum:
            - up
            - down
            - steady
            - calibrating
            - first_report
            - not_comparable
          title: Change State
          type: string
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
        engines:
          additionalProperties:
            $ref: '#/components/schemas/EngineFigures'
          title: Engines
          type: object
        figures:
          $ref: '#/components/schemas/Figures'
        hq_country:
          anyOf:
            - type: string
            - type: 'null'
          title: Hq Country
        medals:
          $ref: '#/components/schemas/Medals'
        mentioned_by:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Mentioned By
        name:
          title: Name
          type: string
        placements:
          items:
            $ref: '#/components/schemas/Placement'
          title: Placements
          type: array
        previous_rank:
          anyOf:
            - type: integer
            - type: 'null'
          title: Previous Rank
        rank:
          anyOf:
            - type: integer
            - type: 'null'
          title: Rank
        rank_change:
          anyOf:
            - type: integer
            - type: 'null'
          description: Previous rank minus current rank; positive means a rise.
          title: Rank Change
        recommended_by:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Recommended By
        score_series:
          items:
            $ref: '#/components/schemas/RankScorePoint'
          title: Score Series
          type: array
        sides:
          anyOf:
            - $ref: '#/components/schemas/PlacementSides'
            - type: 'null'
        slug:
          title: Slug
          type: string
        state:
          anyOf:
            - enum:
                - new
                - returning
                - unranked
              type: string
            - type: 'null'
          title: State
        strength:
          anyOf:
            - type: integer
            - type: 'null'
          title: Strength
      required:
        - brand_id
        - name
        - slug
        - domain
        - hq_country
        - audience
        - figures
        - rank
        - previous_rank
        - rank_change
        - state
        - score_series
        - placements
        - medals
        - sides
        - strength
        - change_state
        - mentioned_by
        - recommended_by
        - engines
      title: BrandRow
      type: object
    RankChangeRow:
      properties:
        brand_id:
          format: uuid
          title: Brand Id
          type: string
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
        name:
          title: Name
          type: string
        previous_rank:
          title: Previous Rank
          type: integer
        rank:
          anyOf:
            - type: integer
            - type: 'null'
          title: Rank
        rank_change:
          anyOf:
            - type: integer
            - type: 'null'
          title: Rank Change
        slug:
          title: Slug
          type: string
        state:
          enum:
            - ranked
            - unranked
            - not_on_roster
          title: State
          type: string
      required:
        - brand_id
        - name
        - slug
        - domain
        - previous_rank
        - rank
        - rank_change
        - state
      title: RankChangeRow
      type: object
    LeaderboardEngineRow:
      properties:
        engine_id:
          title: Engine Id
          type: string
        top_three:
          items:
            $ref: '#/components/schemas/BrandRow'
          title: Top Three
          type: array
      required:
        - engine_id
        - top_three
      title: LeaderboardEngineRow
      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
    LeaderboardPromptRow:
      properties:
        industry:
          title: Industry
          type: string
        language:
          title: Language
          type: string
        prompt_id:
          format: uuid
          title: Prompt Id
          type: string
        text:
          title: Text
          type: string
        winners:
          items:
            format: uuid
            type: string
          title: Winners
          type: array
      required:
        - prompt_id
        - industry
        - text
        - language
        - winners
      title: LeaderboardPromptRow
      type: object
    SourceRow:
      properties:
        answers:
          title: Answers
          type: integer
        citations:
          title: Citations
          type: integer
        domain:
          title: Domain
          type: string
        engines:
          items:
            type: string
          title: Engines
          type: array
        pages:
          $ref: '#/components/schemas/SourcePagesRead'
        rank:
          anyOf:
            - type: integer
            - type: 'null'
          title: Rank
        source_type:
          title: Source Type
          type: string
      required:
        - domain
        - rank
        - source_type
        - citations
        - answers
        - engines
        - pages
      title: SourceRow
      type: object
    EngineFigures:
      properties:
        mentioned:
          $ref: '#/components/schemas/Figure'
        recommended:
          $ref: '#/components/schemas/Figure'
      required:
        - mentioned
        - recommended
      title: EngineFigures
      type: object
    Figures:
      properties:
        heralded_score:
          $ref: '#/components/schemas/Figure'
        mentioned:
          $ref: '#/components/schemas/Figure'
        praised:
          $ref: '#/components/schemas/Figure'
        recommended:
          $ref: '#/components/schemas/Figure'
        understood:
          $ref: '#/components/schemas/Figure'
      required:
        - heralded_score
        - mentioned
        - recommended
        - understood
        - praised
      title: Figures
      type: object
    Medals:
      properties:
        first:
          default: 0
          title: First
          type: integer
        second:
          default: 0
          title: Second
          type: integer
        third:
          default: 0
          title: Third
          type: integer
      required:
        - first
        - second
        - third
      title: Medals
      type: object
    Placement:
      properties:
        industry:
          title: Industry
          type: string
        label:
          title: Label
          type: string
        rank:
          anyOf:
            - type: integer
            - type: 'null'
          title: Rank
        ranked:
          default: 0
          title: Ranked
          type: integer
        score:
          anyOf:
            - type: integer
            - type: 'null'
          title: Score
      required:
        - industry
        - label
        - rank
        - score
        - ranked
      title: Placement
      type: object
    RankScorePoint:
      properties:
        month:
          title: Month
          type: string
        rank:
          anyOf:
            - type: integer
            - type: 'null'
          title: Rank
        score:
          anyOf:
            - type: integer
            - type: 'null'
          title: Score
        state:
          enum:
            - ranked
            - unranked
            - missing
            - not_on_roster
          title: State
          type: string
      required:
        - month
        - rank
        - score
        - state
      title: RankScorePoint
      type: object
    PlacementSides:
      properties:
        ai:
          $ref: '#/components/schemas/SideStanding'
          description: The brand's place and score on the AI board.
        search:
          anyOf:
            - $ref: '#/components/schemas/SideStanding'
            - type: 'null'
          description: Place and score on Search; null where no Search score is available.
      required:
        - ai
        - search
      title: PlacementSides
      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
    SourcePagesRead:
      properties:
        limit:
          title: Limit
          type: integer
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Pass as cursor with the same query to read the next page; null at
            the end.
          title: Next Cursor
        offset:
          title: Offset
          type: integer
        rows:
          items:
            $ref: '#/components/schemas/SourcePage'
          title: Rows
          type: array
        total:
          title: Total
          type: integer
        withheld:
          description: Ranks present in the module whose rows are withheld.
          items:
            type: integer
          title: Withheld
          type: array
      required:
        - meta
        - next_cursor
        - total
        - limit
        - offset
        - withheld
        - rows
      title: SourcePagesRead
      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
    SideStanding:
      properties:
        rank:
          anyOf:
            - type: integer
            - type: 'null'
          title: Rank
        score:
          anyOf:
            - type: integer
            - type: 'null'
          title: Score
      required:
        - rank
        - score
      title: SideStanding
      type: object
    SourcePage:
      properties:
        citations:
          title: Citations
          type: integer
        kind:
          anyOf:
            - type: string
            - type: 'null'
          title: Kind
        mentions:
          anyOf:
            - items:
                format: uuid
                type: string
              type: array
            - type: 'null'
          title: Mentions
        recommends:
          anyOf:
            - items:
                format: uuid
                type: string
              type: array
            - type: 'null'
          title: Recommends
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        url:
          title: Url
          type: string
      required:
        - url
        - title
        - kind
        - citations
        - mentions
        - recommends
      title: SourcePage
      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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.