---
title: "Get Brands Report"
method: POST
path: "/reports/brands"
tags: ["Reports"]
---

# Get Brands Report

`POST /reports/brands`

Get a report on Brands.

## Aggregation Formulas

When aggregating results across multiple rows/dimensions, use the following formulas:

- **sentiment**: `((sum(sentiment_sum) / sum(sentiment_count)) / 2 + 0.5) * 100`
- **position**: `sum(position_sum) / sum(position_count)`
- **visibility**: `sum(visibility_count) / sum(visibility_total)`
- **share_of_voice**: `mention_count / sum(mention_count)`

## `filters` vs `having`

`filters` are **pre-aggregation** row filters (applied as WHERE before GROUP BY). They shrink both the numerator and the denominator of ratio metrics. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `brand_id`. Note that `brand_id` in `filters` shrinks `share_of_voice`'s denominator too — so filtering to one brand collapses SoV to 1.0. Use `having` for `brand_id` if you want SoV preserved.

`having` are **post-aggregation** row filters (applied as HAVING after GROUP BY). They select which aggregated rows are returned and do **not** shrink ratio-metric denominators. Filtering `{field: "brand_id", values: [X]}` here returns only brand X's row, but `share_of_voice` still divides X's mentions by mentions across all in-scope brands — so SoV stays in [0, 1]. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `brand_id`.

Population fields (`model_id` etc.) are also allowed in `having` but require the matching value in `dimensions` so the column appears in GROUP BY; otherwise the request is rejected.

When `dimensions` are requested, the `share_of_voice` denominator follows the same grouping as the numerator. Requesting `prompt_id` as a dimension produces per-(brand × prompt) rows whose `share_of_voice` is the brand's mentions in that prompt divided by all brands' mentions in that prompt.

## Query parameters

- `project_id` string — Required if using a company api key

## Request body

- object
  - `project_id` string — Required if using a company api key
  - `limit` number
  - `offset` number
  - `start_date` string, date — full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21
  - `end_date` string, date — full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21
  - `dimensions` string[] — Dimensions to break down the report by.
  - `filters` union[] — Pre-aggregation row filters (applied as WHERE before grouping). Shrinks both the numerator and the denominator of ratio metrics. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `brand_id`. Filtering by `brand_id` here also shrinks `share_of_voice`'s denominator — so SoV collapses to 1.0 when scoping to a single brand. If you want SoV preserved (X's share against all in-scope brands), put `brand_id` in `having` instead. Multiple filters are AND'd.
    - union
      - object — Deprecated: use model_channel_id filter instead
        - `field` 'model_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'model_channel_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'tag_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'topic_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'prompt_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'country_code', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'chat_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'brand_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
  - `having` union[] — Post-aggregation row filters (applied as HAVING after grouping). Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `brand_id` — population fields require the matching value in `dimensions` so the column appears in GROUP BY. Selects which aggregated rows are returned without shrinking ratio-metric denominators. Multiple filters are AND'd together.
    - union
      - object — Deprecated: use model_channel_id filter instead
        - `field` 'model_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'model_channel_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'tag_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'topic_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'prompt_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'country_code', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'chat_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'brand_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
  - `order_by` object[] — Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.
    - `field` 'visibility' | 'visibility_count' | 'mention_count' | 'sentiment' | 'position' | 'share_of_voice' | 'date' | 'week' | 'month', required
    - `direction` 'asc' | 'desc'

## Response `200`

Success

- object — Success
  - `data` object[], required
    - `brand` object, required
      - `id` string, required
      - `name` string, required
    - `prompt` object
      - `id` string, required
    - `model` object — Deprecated: use model_channel instead
      - `id` string, required
    - `model_channel` object
      - `id` string, required
    - `tag` object
      - `id` string, required
    - `topic` object
      - `id` string, required
    - `country_code` string
    - `chat` object
      - `id` string, required
    - `date` string
    - `week` string — Start (Monday) of the ISO week bucket.
    - `month` string — First day of the month bucket.
    - `share_of_voice` number — Share of total mentions attributed to this brand within the row's dimension grouping. The denominator sums mentions across all brands within the same dimension values (e.g. when grouping by `prompt_id`, across all brands within that prompt). Pre-aggregation `filters` shrink both numerator and denominator together — filtering by `brand_id` here collapses SoV to 1.0. Post-aggregation `having` (e.g. `brand_id`) selects which rows are returned without shrinking the denominator, so SoV stays in [0, 1].
    - `mention_count` number, required
    - `visibility` number, required
    - `visibility_count` number, required
    - `visibility_total` number, required
    - `sentiment` number
    - `sentiment_sum` number
    - `sentiment_count` number
    - `position` number
    - `position_sum` number
    - `position_count` number

---

[API](https://skmtc.net/peec/apis/peec-ai-customer-api.md) · [All operations](https://skmtc.net/peec/apis/peec-ai-customer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/peec/peec-ai-customer-api/revisions/92840a1bffa7/schema)