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

# Run a brand-metrics report (dimensions, filters, ordering)



## OpenAPI

````yaml https://app.mavel.ai/api/v1/openapi.json post /reports/brands
openapi: 3.0.3
info:
  title: Mavel REST API
  version: v1
  description: >-
    REST API for Mavel. Authentication: pass `X-API-Key: <key>` header.
    Rate-limited at 200 req/min/project. Plan tier: Enterprise (or Scale+ on
    Agency tier).
servers:
  - url: /api/v1
security:
  - ApiKeyAuth: []
paths:
  /reports/brands:
    post:
      tags:
        - Reports
      summary: Run a brand-metrics report (dimensions, filters, ordering)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
                  format: uuid
                start_date:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}$
                end_date:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}$
                dimensions:
                  type: array
                  items:
                    type: string
                filters:
                  type: array
                  items:
                    type: object
                    additionalProperties:
                      nullable: true
                order_by:
                  type: array
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                      direction:
                        type: string
                        enum:
                          - asc
                          - desc
                    required:
                      - field
                      - direction
                limit:
                  type: integer
                  minimum: 1
                  maximum: 1000
                offset:
                  type: integer
                  minimum: 0
              required:
                - project_id
                - start_date
                - end_date
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  rows:
                    type: array
                    items:
                      type: object
                      properties:
                        brand_id:
                          type: string
                          format: uuid
                        display_name:
                          type: string
                        visibility_count:
                          type: integer
                          description: >-
                            Successful-chat count in which this brand was
                            mentioned, over the requested window (the numerator
                            of the visibility ratio). Divide by
                            `visibility_total` for a ratio; never sum/compare
                            `visibility_count` across brands without dividing
                            first — a brand with more tracked prompts naturally
                            has a larger raw count.
                        visibility_total:
                          type: integer
                          description: >-
                            Successful-chat count for the (prompt, channel,
                            country, date) buckets this brand is tracked in —
                            the denominator of the visibility ratio
                            (`visibility_count / visibility_total`). Applied
                            identically to every brand tracked in the same
                            bucket, so it is NOT a per-brand-computed figure:
                            summing it across MULTIPLE brands inflates the
                            denominator. Always take the ratio within one
                            brand's own row.
                        mention_count:
                          type: integer
                          description: >-
                            Raw brand-name mention count across the window's
                            chats — can exceed `visibility_count` when a chat
                            mentions the brand more than once.
                      required:
                        - brand_id
                        - display_name
                        - visibility_count
                        - visibility_total
                        - mention_count
                required:
                  - rows
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    pattern: ^[A-Z0-9]+(?:_[A-Z0-9]+)*$
                  message:
                    type: string
                  statusCode:
                    type: integer
                  meta:
                    type: object
                    additionalProperties:
                      nullable: true
                required:
                  - code
                  - message
                  - statusCode
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````