> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfacd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Report Field Values

> The values one scope or filter field accepts for the project, so a condition can be filled without guessing. A key field lists its keys with their names as labels: brand UUIDs (`brand_uuid`; primary brand first; `brand_uuid` and `mentions_brand` start with `competitors`, the brands marked as competitors), narrative, theme, prompt, topic (`no_topic` first) and tag (`untagged` first) UUIDs, platform slugs (`service_provider`) and country codes (`country_code`), so a client never maps codes to names itself. A name field (`brand`, `topic`, `tag`, `prompt`, `service`, `country`, `narrative`, `theme`) lists the names. Also listed: the domains the project's answers cite (most cited first) and the fixed vocabularies (`page_type`, `category`, `brand_on_page`, `mention_sentiment`, `page_sentiment`, `narrative_sentiment`, `carries_sentiment`).

Put the returned `value` in the condition; `label` and `description` are for people. `search` matches the label case-insensitively (prompts, domains and narratives search in the database). `total` counts the matches before `limit`. The narrative and theme fields need the Reputation capability.



## OpenAPI

````yaml /openapi.json get /api/v1/projects/{project}/reports/values/{field}
openapi: 3.1.0
info:
  title: Surfacd Public API
  version: 1.0.0
  description: >-
    Public API for Surfacd. Team-scoped operations live under
    `/api/v1/team/...`; project collections live under `/api/v1/projects`;
    project-scoped operations live under `/api/v1/projects/{project}/...`. All
    endpoints require a Bearer team API key created in Team Settings. The API
    key selects the team for team-level and collection endpoints. Reports
    default to currently monitored, nondeprecated platforms. Explicit platform
    filters can include deprecated or no-longer-monitored platforms with project
    history, provided they remain enabled globally. Admin-disabled platforms are
    excluded; no eligible default platforms means no default answers. Use
    `copilot` for historical standalone Copilot data and `bing_ai_mode` for Bing
    AI Mode; these are separate platforms. Deprecated platforms are not
    available for new monitoring through `/api/v1/platforms`.
servers:
  - url: https://app.surfacd.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Projects
    description: Project management endpoints.
  - name: Prompts
    description: Prompt management endpoints.
  - name: Team
    description: Team settings and plan details for the current team.
  - name: Reporting
    description: >-
      Read-only reporting endpoints for projects (brand rankings, mentions,
      visibility, matrix analysis, source data) and single AI answers.
  - name: Reference
    description: Reference data used by create, update, and reporting filters.
  - name: Tags
    description: Project tag management endpoints.
  - name: Reputation
    description: >-
      Read-only reputation analytics for a project: sentiment overview and
      trends, themes, narratives, the AI responses behind them, and the sources
      those responses cite. Requires the Reputation capability on the project's
      team; without it these endpoints return `403`.
  - name: Reports
    description: >-
      The report query endpoint. One `POST` per report entity (`visibility`,
      `sources`, `narratives`) takes dimensions, measures, filters, an optional
      compare window and paging, and returns a dataset any renderer can draw.
      The schema and values endpoints describe what a query accepts. See the
      Reports API guide in the docs for worked examples of every app report.
  - name: Personas
    description: >-
      Project persona management endpoints. A persona is a buyer you want AI to
      recommend you to; a prompt can be asked from one persona's point of view,
      and reporting can be filtered or broken down by persona. Prompts asked
      without a persona are `no_persona` ("No persona") here and in reports, and
      the Baseline in the app. Personas are in beta and available to all teams
      with API access.
paths:
  /api/v1/projects/{project}/reports/values/{field}:
    parameters:
      - $ref: '#/components/parameters/ProjectUuid'
      - name: field
        in: path
        required: true
        description: >-
          A scope or filter field with a value list. A key field lists its keys
          with their names as labels, and the reserved values first
          (`competitors`, `untagged`, `no_topic`, `no_persona`); a name field
          lists each name once, as both value and label.
        schema:
          type: string
          enum:
            - brand_uuid
            - brand
            - mentions_brand
            - page_brand
            - answer_brand
            - narrative_uuid
            - narrative
            - carries_narrative
            - theme_uuid
            - theme
            - carries_theme
            - prompt_uuid
            - prompt
            - topic_uuid
            - topic
            - persona_uuid
            - persona
            - tag_uuid
            - tag
            - branded
            - buying_stage
            - service_provider
            - service
            - country_code
            - country
            - domain
            - cites_domain
            - page_type
            - category
            - brand_on_page
            - mention_sentiment
            - page_sentiment
            - narrative_sentiment
            - carries_sentiment
    get:
      tags:
        - Reports
      summary: List Report Field Values
      description: >-
        The values one scope or filter field accepts for the project, so a
        condition can be filled without guessing. A key field lists its keys
        with their names as labels: brand UUIDs (`brand_uuid`; primary brand
        first; `brand_uuid` and `mentions_brand` start with `competitors`, the
        brands marked as competitors), narrative, theme, prompt, topic
        (`no_topic` first) and tag (`untagged` first) UUIDs, platform slugs
        (`service_provider`) and country codes (`country_code`), so a client
        never maps codes to names itself. A name field (`brand`, `topic`, `tag`,
        `prompt`, `service`, `country`, `narrative`, `theme`) lists the names.
        Also listed: the domains the project's answers cite (most cited first)
        and the fixed vocabularies (`page_type`, `category`, `brand_on_page`,
        `mention_sentiment`, `page_sentiment`, `narrative_sentiment`,
        `carries_sentiment`).


        Put the returned `value` in the condition; `label` and `description` are
        for people. `search` matches the label case-insensitively (prompts,
        domains and narratives search in the database). `total` counts the
        matches before `limit`. The narrative and theme fields need the
        Reputation capability.
      operationId: v1ProjectsReportsValues
      parameters:
        - name: search
          in: query
          required: false
          schema:
            type: string
            maxLength: 100
          description: Case-insensitive match on the label.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
      responses:
        '200':
          description: The field's values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportFieldValues'
              examples:
                brand_uuid:
                  summary: 'A key field: brand UUIDs with their names'
                  value:
                    field: brand_uuid
                    search: ''
                    total: 26
                    values:
                      - value: competitors
                        label: Competitors
                        description: brands marked as competitors
                      - value: 4e1f77d6-35d8-4a29-9fb6-d83e51469b35
                        label: Apple
                        description: primary brand
                      - value: bb908fbe-ad42-4a75-8555-648b5298a159
                        label: Anker
                        description: null
                service_provider:
                  summary: 'A key field: platform slugs with their names'
                  value:
                    field: service_provider
                    search: google
                    total: 2
                    values:
                      - value: google_ai_mode
                        label: Google AI Mode
                        description: null
                      - value: google_ai_overviews
                        label: Google AI Overviews
                        description: null
                topic:
                  summary: 'A name field: topic names'
                  value:
                    field: topic
                    search: pric
                    total: 1
                    values:
                      - value: Pricing
                        label: Pricing
                        description: null
        '403':
          $ref: '#/components/responses/ReportEntitlement'
        '404':
          description: Project not found in the current team.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  parameters:
    ProjectUuid:
      name: project
      in: path
      required: true
      description: Project UUID.
      schema:
        type: string
        format: uuid
  schemas:
    ReportFieldValues:
      type: object
      properties:
        field:
          type: string
        search:
          type: string
        total:
          type: integer
          description: Matches before `limit` was applied.
        values:
          type: array
          items:
            $ref: '#/components/schemas/ReportFieldValue'
      required:
        - field
        - search
        - total
        - values
    ReportFieldValue:
      type: object
      properties:
        value:
          type: string
          description: 'What to put in the condition: a key, a name or a vocabulary value.'
        label:
          type: string
        description:
          type: string
          nullable: true
          examples:
            - primary brand
            - 2127 citations
            - negative · Pricing
      required:
        - value
        - label
        - description
    ValidationError:
      type: object
      description: Returned when one or more request parameters fail validation.
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - message
        - errors
  responses:
    ReportEntitlement:
      description: >-
        The query reads reputation data (the `narratives` entity, or a
        `carries_narrative`, `carries_theme` or `carries_sentiment` scope
        condition) and the team does not have the Reputation capability.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
            required:
              - message
    ValidationError:
      description: Validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: >-
        Team API key created in Team Settings. Use it with URLs for the same
        team.

````

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