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

> Leaderboard page catalogue and available filters. No credential required.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/leaderboards/facets
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/facets:
    get:
      tags:
        - v1
      summary: Get Facets
      description: >-
        Leaderboard page catalogue and available filters. No credential
        required.
      operationId: getLeaderboardFacets
      parameters:
        - 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
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FacetsRead'
          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:
    FacetsRead:
      properties:
        facets:
          $ref: '#/components/schemas/Facets'
        meta:
          $ref: '#/components/schemas/Meta'
          description: Normalized query and newest included scan.
        month:
          anyOf:
            - type: string
            - type: 'null'
          title: Month
        pages:
          items:
            $ref: '#/components/schemas/LeaderboardPage'
          title: Pages
          type: array
        score_bands:
          items:
            $ref: '#/components/schemas/ScoreBand'
          title: Score Bands
          type: array
      required:
        - meta
        - facets
        - month
        - pages
        - score_bands
      title: FacetsRead
      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
    Facets:
      properties:
        countries:
          items:
            type: string
          title: Countries
          type: array
        engines:
          items:
            $ref: '#/components/schemas/EngineFacet'
          title: Engines
          type: array
        industries:
          items:
            $ref: '#/components/schemas/IndustryFacet'
          title: Industries
          type: array
        origins:
          items:
            type: string
          title: Origins
          type: array
      required:
        - industries
        - countries
        - engines
        - origins
      title: Facets
      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
    LeaderboardPage:
      properties:
        brand_count:
          description: Brands in this leaderboard page.
          title: Brand Count
          type: integer
        canonical:
          title: Canonical
          type: string
        canonical_parent:
          anyOf:
            - type: string
            - type: 'null'
          title: Canonical Parent
        description:
          title: Description
          type: string
        featured_position:
          anyOf:
            - type: integer
            - type: 'null'
          title: Featured Position
        filters:
          $ref: '#/components/schemas/LeaderboardFilters'
        indexed:
          title: Indexed
          type: boolean
        leader:
          anyOf:
            - $ref: '#/components/schemas/LeaderboardLeader'
            - type: 'null'
        path:
          title: Path
          type: string
        ranked:
          title: Ranked
          type: boolean
        title:
          title: Title
          type: string
      required:
        - filters
        - path
        - ranked
        - title
        - description
        - brand_count
        - indexed
        - canonical_parent
        - canonical
        - featured_position
        - leader
      title: LeaderboardPage
      type: object
    ScoreBand:
      description: 'One band of the Heralded Score: its word and the scores it spans.'
      properties:
        high:
          title: High
          type: integer
        label:
          title: Label
          type: string
        low:
          title: Low
          type: integer
      required:
        - label
        - low
        - high
      title: ScoreBand
      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
    EngineFacet:
      properties:
        engine_id:
          enum:
            - perplexity
            - gemini
            - openai
            - google_aio
            - ai_mode
            - copilot
            - claude
          title: Engine Id
          type: string
        label:
          title: Label
          type: string
        slug:
          title: Slug
          type: string
      required:
        - engine_id
        - slug
        - label
      title: EngineFacet
      type: object
    IndustryFacet:
      properties:
        default_audience:
          title: Default Audience
          type: string
        label:
          title: Label
          type: string
        plural_noun:
          title: Plural Noun
          type: string
        slug:
          title: Slug
          type: string
      required:
        - slug
        - label
        - plural_noun
        - default_audience
      title: IndustryFacet
      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
    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
    LeaderboardLeader:
      properties:
        brand_id:
          format: uuid
          title: Brand Id
          type: string
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
        name:
          title: Name
          type: string
        slug:
          title: Slug
          type: string
      required:
        - brand_id
        - name
        - slug
        - domain
      title: LeaderboardLeader
      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

````

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