> ## 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. # Brand Mentions > Returns paginated brand mentions matched within the requested date range. Supports filtering by brand, AI service, country, tag, topic, prompt, rank range, sentiment, and free-text search across snippets. ## OpenAPI ````yaml /openapi.json get /api/v1/projects/{project}/mentions 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. servers: - url: https://app.surfacd.com description: Production security: - bearerAuth: [] tags: - name: Projects description: Project management endpoints. Reads only in this version. - name: Prompts description: Prompt management endpoints. Reads only in this version. - 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). - name: Reference description: Reference data used by create, update, and reporting filters. - name: Tags description: Project tag management endpoints. paths: /api/v1/projects/{project}/mentions: parameters: - $ref: '#/components/parameters/ProjectUuid' get: tags: - Reporting summary: Brand Mentions description: >- Returns paginated brand mentions matched within the requested date range. Supports filtering by brand, AI service, country, tag, topic, prompt, rank range, sentiment, and free-text search across snippets. operationId: v1ProjectsMentions parameters: - name: start_date in: query required: true schema: type: string format: date - name: end_date in: query required: true schema: type: string format: date - name: search_term in: query required: false schema: type: string maxLength: 255 - name: brands in: query required: false schema: type: array items: type: string format: uuid maxItems: 1 description: Brand UUID filter. Pass a single brand UUID as `brands[]=...`. style: form explode: true - name: services in: query required: false schema: type: array items: type: string description: >- AI platform provider filters such as `chatgpt` or `perplexity`. Discover providers with `GET /api/v1/platforms`. style: form explode: true - name: countries in: query required: false schema: type: array items: type: string description: >- Country code filters such as `US` or `GB`. Discover codes with `GET /api/v1/countries`. style: form explode: true - name: tags in: query required: false schema: type: array items: type: string format: uuid description: >- Tag UUID filters. Discover tag UUIDs with `GET /api/v1/projects/{project}/tags`. style: form explode: true - name: topics in: query required: false schema: type: array items: type: string description: >- Topic UUID filters. Use `no_topic` for prompts without a topic. Discover topic UUIDs with `GET /api/v1/projects/{project}/topics`. style: form explode: true - name: prompt in: query required: false schema: type: string format: uuid description: Prompt UUID filter. - name: sentiments in: query required: false schema: type: string description: >- Comma-separated list of sentiments. Allowed values: `positive`, `negative`, `neutral`. - name: rank_from in: query required: false schema: type: integer minimum: 1 - name: rank_to in: query required: false schema: type: integer minimum: 1 - name: per_page in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 - name: sort_by in: query required: false schema: type: string enum: - rank - name: sort_direction in: query required: false schema: type: string enum: - asc - desc default: asc responses: '200': description: Paginated brand mentions. content: application/json: schema: $ref: '#/components/schemas/PaginatedBrandMention' '422': $ref: '#/components/responses/ValidationError' components: parameters: ProjectUuid: name: project in: path required: true description: Project UUID. schema: type: string format: uuid schemas: PaginatedBrandMention: type: object properties: data: type: array items: $ref: '#/components/schemas/BrandMention' links: $ref: '#/components/schemas/PaginationLinks' meta: $ref: '#/components/schemas/PaginationMeta' required: - data - meta BrandMention: type: object description: >- Public brand mention representation. Internal numeric IDs are not exposed; nested related objects use public UUIDs or provider/country identifiers where present. properties: sentiment: type: string description: '`positive`, `negative`, or `neutral`.' salience_score: type: string description: Returned as a string for precision; parse to float on the client. rank: type: integer mention_snippet: type: - string - 'null' created_at: type: string format: date-time updated_at: type: string format: date-time required: - sentiment - salience_score - rank - mention_snippet - created_at - updated_at PaginationLinks: type: object properties: first: type: - string - 'null' last: type: - string - 'null' prev: type: - string - 'null' next: type: - string - 'null' required: - first - last - prev - next PaginationMeta: type: object properties: current_page: type: integer from: type: - integer - 'null' last_page: type: integer links: type: array items: $ref: '#/components/schemas/PaginationMetaLink' path: type: - string - 'null' per_page: type: integer to: type: - integer - 'null' total: type: integer required: - current_page - last_page - per_page - total 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 PaginationMetaLink: type: object properties: url: type: - string - 'null' label: type: string active: type: boolean required: - url - label - active responses: 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. ````