> ## Documentation Index > Fetch the complete documentation index at: https://docs.peec.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Brands Report > 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. ## OpenAPI ````yaml https://api.peec.ai/customer/v1/openapi/json post /reports/brands openapi: 3.0.3 info: title: Peec AI Customer API description: Development documentation version: 1.0.0 contact: name: Peec AI Team email: support@peec.ai servers: - url: https://api.peec.ai/customer/v1 security: [] paths: /reports/brands: post: tags: - Reports summary: Get Brands Report description: >- 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. operationId: postReportsBrands parameters: - name: project_id in: query required: false schema: description: Required if using a company api key example: or_f45b94ba-5e35-4982-93ed-285e72ee14eb type: string requestBody: required: true content: application/json: schema: type: object properties: project_id: description: Required if using a company api key example: or_f45b94ba-5e35-4982-93ed-285e72ee14eb type: string limit: default: 1000 type: number minimum: 1 maximum: 10000 offset: default: 0 type: number minimum: 0 start_date: default: '2026-01-01' description: >- full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21 example: '2025-09-22' type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ end_date: default: '2026-01-01' description: >- full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21 example: '2025-09-22' type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ dimensions: example: - tag_id - model_id description: Dimensions to break down the report by. type: array items: type: string enum: - prompt_id - model_id - model_channel_id - tag_id - topic_id - date - week - month - country_code - chat_id filters: description: >- 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. example: - field: model_id operator: in values: - gpt-4o-search type: array items: anyOf: - type: object properties: field: type: string enum: - model_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - chatgpt-scraper - gpt-4o - gpt-4o-search - gpt-3.5-turbo - llama-sonar - perplexity-scraper - sonar - gemini-2.5-flash - gemini-scraper - google-ai-overview-scraper - google-ai-mode-scraper - llama-3.3-70b-instruct - deepseek-r1 - deepseek-v4-pro - claude-3.5-haiku - claude-haiku-4.5 - claude-sonnet-4 - grok-scraper - microsoft-copilot-scraper - grok-4 - grok-4.3 - qwen-3-6-plus - qwen-3-7-plus - amazon-rufus-scraper required: - field - operator - values deprecated: true description: 'Deprecated: use model_channel_id filter instead' - type: object properties: field: type: string enum: - model_channel_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - openai-0 - openai-1 - qwen-0 - openai-2 - perplexity-0 - perplexity-1 - google-0 - google-1 - google-2 - google-3 - anthropic-0 - anthropic-1 - deepseek-0 - meta-0 - xai-0 - xai-1 - microsoft-0 - amazon-0 required: - field - operator - values - type: object properties: field: type: string enum: - tag_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - topic_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - prompt_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - country_code operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - AE - AL - AM - AR - AT - AU - BA - BE - BG - BH - BO - BR - BS - BY - CA - CH - CL - CN - CO - CR - CY - CZ - DE - DK - DO - EC - EE - EG - ES - FI - FR - GB - GE - GH - GR - GT - HK - HN - HR - HU - ID - IE - IL - IN - IQ - IS - IT - JO - JP - KR - KW - LB - LI - LT - LU - LV - MA - MD - ME - MK - MT - MX - MY - NG - NI - NL - 'NO' - NZ - OM - PK - PA - PE - PH - PL - PT - PY - PS - QA - RO - RS - SA - SE - SG - SI - SK - SV - TH - TN - TR - TW - UA - US - UY - VE - VN - ZA - AD - AF - AS - AZ - BB - BQ - CG - CI - CM - CW - DM - DZ - FO - GF - GP - JM - KG - KH - KI - KZ - LK - LR - LS - MW - NC - PG - TD - TF - UG - VU - ZW required: - field - operator - values - type: object properties: field: type: string enum: - chat_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - brand_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values having: description: >- 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. example: - field: brand_id operator: in values: - kw_abc123 type: array items: anyOf: - type: object properties: field: type: string enum: - model_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - chatgpt-scraper - gpt-4o - gpt-4o-search - gpt-3.5-turbo - llama-sonar - perplexity-scraper - sonar - gemini-2.5-flash - gemini-scraper - google-ai-overview-scraper - google-ai-mode-scraper - llama-3.3-70b-instruct - deepseek-r1 - deepseek-v4-pro - claude-3.5-haiku - claude-haiku-4.5 - claude-sonnet-4 - grok-scraper - microsoft-copilot-scraper - grok-4 - grok-4.3 - qwen-3-6-plus - qwen-3-7-plus - amazon-rufus-scraper required: - field - operator - values deprecated: true description: 'Deprecated: use model_channel_id filter instead' - type: object properties: field: type: string enum: - model_channel_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - openai-0 - openai-1 - qwen-0 - openai-2 - perplexity-0 - perplexity-1 - google-0 - google-1 - google-2 - google-3 - anthropic-0 - anthropic-1 - deepseek-0 - meta-0 - xai-0 - xai-1 - microsoft-0 - amazon-0 required: - field - operator - values - type: object properties: field: type: string enum: - tag_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - topic_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - prompt_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - country_code operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - AE - AL - AM - AR - AT - AU - BA - BE - BG - BH - BO - BR - BS - BY - CA - CH - CL - CN - CO - CR - CY - CZ - DE - DK - DO - EC - EE - EG - ES - FI - FR - GB - GE - GH - GR - GT - HK - HN - HR - HU - ID - IE - IL - IN - IQ - IS - IT - JO - JP - KR - KW - LB - LI - LT - LU - LV - MA - MD - ME - MK - MT - MX - MY - NG - NI - NL - 'NO' - NZ - OM - PK - PA - PE - PH - PL - PT - PY - PS - QA - RO - RS - SA - SE - SG - SI - SK - SV - TH - TN - TR - TW - UA - US - UY - VE - VN - ZA - AD - AF - AS - AZ - BB - BQ - CG - CI - CM - CW - DM - DZ - FO - GF - GP - JM - KG - KH - KI - KZ - LK - LR - LS - MW - NC - PG - TD - TF - UG - VU - ZW required: - field - operator - values - type: object properties: field: type: string enum: - chat_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - brand_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values order_by: description: >- 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. example: - field: visibility direction: desc type: array items: type: object properties: field: type: string enum: - visibility - visibility_count - mention_count - sentiment - position - share_of_voice - date - week - month direction: default: desc type: string enum: - asc - desc required: - field application/x-www-form-urlencoded: schema: type: object properties: project_id: description: Required if using a company api key example: or_f45b94ba-5e35-4982-93ed-285e72ee14eb type: string limit: default: 1000 type: number minimum: 1 maximum: 10000 offset: default: 0 type: number minimum: 0 start_date: default: '2026-01-01' description: >- full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21 example: '2025-09-22' type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ end_date: default: '2026-01-01' description: >- full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21 example: '2025-09-22' type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ dimensions: example: - tag_id - model_id description: Dimensions to break down the report by. type: array items: type: string enum: - prompt_id - model_id - model_channel_id - tag_id - topic_id - date - week - month - country_code - chat_id filters: description: >- 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. example: - field: model_id operator: in values: - gpt-4o-search type: array items: anyOf: - type: object properties: field: type: string enum: - model_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - chatgpt-scraper - gpt-4o - gpt-4o-search - gpt-3.5-turbo - llama-sonar - perplexity-scraper - sonar - gemini-2.5-flash - gemini-scraper - google-ai-overview-scraper - google-ai-mode-scraper - llama-3.3-70b-instruct - deepseek-r1 - deepseek-v4-pro - claude-3.5-haiku - claude-haiku-4.5 - claude-sonnet-4 - grok-scraper - microsoft-copilot-scraper - grok-4 - grok-4.3 - qwen-3-6-plus - qwen-3-7-plus - amazon-rufus-scraper required: - field - operator - values deprecated: true description: 'Deprecated: use model_channel_id filter instead' - type: object properties: field: type: string enum: - model_channel_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - openai-0 - openai-1 - qwen-0 - openai-2 - perplexity-0 - perplexity-1 - google-0 - google-1 - google-2 - google-3 - anthropic-0 - anthropic-1 - deepseek-0 - meta-0 - xai-0 - xai-1 - microsoft-0 - amazon-0 required: - field - operator - values - type: object properties: field: type: string enum: - tag_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - topic_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - prompt_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - country_code operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - AE - AL - AM - AR - AT - AU - BA - BE - BG - BH - BO - BR - BS - BY - CA - CH - CL - CN - CO - CR - CY - CZ - DE - DK - DO - EC - EE - EG - ES - FI - FR - GB - GE - GH - GR - GT - HK - HN - HR - HU - ID - IE - IL - IN - IQ - IS - IT - JO - JP - KR - KW - LB - LI - LT - LU - LV - MA - MD - ME - MK - MT - MX - MY - NG - NI - NL - 'NO' - NZ - OM - PK - PA - PE - PH - PL - PT - PY - PS - QA - RO - RS - SA - SE - SG - SI - SK - SV - TH - TN - TR - TW - UA - US - UY - VE - VN - ZA - AD - AF - AS - AZ - BB - BQ - CG - CI - CM - CW - DM - DZ - FO - GF - GP - JM - KG - KH - KI - KZ - LK - LR - LS - MW - NC - PG - TD - TF - UG - VU - ZW required: - field - operator - values - type: object properties: field: type: string enum: - chat_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - brand_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values having: description: >- 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. example: - field: brand_id operator: in values: - kw_abc123 type: array items: anyOf: - type: object properties: field: type: string enum: - model_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - chatgpt-scraper - gpt-4o - gpt-4o-search - gpt-3.5-turbo - llama-sonar - perplexity-scraper - sonar - gemini-2.5-flash - gemini-scraper - google-ai-overview-scraper - google-ai-mode-scraper - llama-3.3-70b-instruct - deepseek-r1 - deepseek-v4-pro - claude-3.5-haiku - claude-haiku-4.5 - claude-sonnet-4 - grok-scraper - microsoft-copilot-scraper - grok-4 - grok-4.3 - qwen-3-6-plus - qwen-3-7-plus - amazon-rufus-scraper required: - field - operator - values deprecated: true description: 'Deprecated: use model_channel_id filter instead' - type: object properties: field: type: string enum: - model_channel_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - openai-0 - openai-1 - qwen-0 - openai-2 - perplexity-0 - perplexity-1 - google-0 - google-1 - google-2 - google-3 - anthropic-0 - anthropic-1 - deepseek-0 - meta-0 - xai-0 - xai-1 - microsoft-0 - amazon-0 required: - field - operator - values - type: object properties: field: type: string enum: - tag_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - topic_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - prompt_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - country_code operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - AE - AL - AM - AR - AT - AU - BA - BE - BG - BH - BO - BR - BS - BY - CA - CH - CL - CN - CO - CR - CY - CZ - DE - DK - DO - EC - EE - EG - ES - FI - FR - GB - GE - GH - GR - GT - HK - HN - HR - HU - ID - IE - IL - IN - IQ - IS - IT - JO - JP - KR - KW - LB - LI - LT - LU - LV - MA - MD - ME - MK - MT - MX - MY - NG - NI - NL - 'NO' - NZ - OM - PK - PA - PE - PH - PL - PT - PY - PS - QA - RO - RS - SA - SE - SG - SI - SK - SV - TH - TN - TR - TW - UA - US - UY - VE - VN - ZA - AD - AF - AS - AZ - BB - BQ - CG - CI - CM - CW - DM - DZ - FO - GF - GP - JM - KG - KH - KI - KZ - LK - LR - LS - MW - NC - PG - TD - TF - UG - VU - ZW required: - field - operator - values - type: object properties: field: type: string enum: - chat_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - brand_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values order_by: description: >- 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. example: - field: visibility direction: desc type: array items: type: object properties: field: type: string enum: - visibility - visibility_count - mention_count - sentiment - position - share_of_voice - date - week - month direction: default: desc type: string enum: - asc - desc required: - field multipart/form-data: schema: type: object properties: project_id: description: Required if using a company api key example: or_f45b94ba-5e35-4982-93ed-285e72ee14eb type: string limit: default: 1000 type: number minimum: 1 maximum: 10000 offset: default: 0 type: number minimum: 0 start_date: default: '2026-01-01' description: >- full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21 example: '2025-09-22' type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ end_date: default: '2026-01-01' description: >- full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21 example: '2025-09-22' type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ dimensions: example: - tag_id - model_id description: Dimensions to break down the report by. type: array items: type: string enum: - prompt_id - model_id - model_channel_id - tag_id - topic_id - date - week - month - country_code - chat_id filters: description: >- 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. example: - field: model_id operator: in values: - gpt-4o-search type: array items: anyOf: - type: object properties: field: type: string enum: - model_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - chatgpt-scraper - gpt-4o - gpt-4o-search - gpt-3.5-turbo - llama-sonar - perplexity-scraper - sonar - gemini-2.5-flash - gemini-scraper - google-ai-overview-scraper - google-ai-mode-scraper - llama-3.3-70b-instruct - deepseek-r1 - deepseek-v4-pro - claude-3.5-haiku - claude-haiku-4.5 - claude-sonnet-4 - grok-scraper - microsoft-copilot-scraper - grok-4 - grok-4.3 - qwen-3-6-plus - qwen-3-7-plus - amazon-rufus-scraper required: - field - operator - values deprecated: true description: 'Deprecated: use model_channel_id filter instead' - type: object properties: field: type: string enum: - model_channel_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - openai-0 - openai-1 - qwen-0 - openai-2 - perplexity-0 - perplexity-1 - google-0 - google-1 - google-2 - google-3 - anthropic-0 - anthropic-1 - deepseek-0 - meta-0 - xai-0 - xai-1 - microsoft-0 - amazon-0 required: - field - operator - values - type: object properties: field: type: string enum: - tag_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - topic_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - prompt_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - country_code operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - AE - AL - AM - AR - AT - AU - BA - BE - BG - BH - BO - BR - BS - BY - CA - CH - CL - CN - CO - CR - CY - CZ - DE - DK - DO - EC - EE - EG - ES - FI - FR - GB - GE - GH - GR - GT - HK - HN - HR - HU - ID - IE - IL - IN - IQ - IS - IT - JO - JP - KR - KW - LB - LI - LT - LU - LV - MA - MD - ME - MK - MT - MX - MY - NG - NI - NL - 'NO' - NZ - OM - PK - PA - PE - PH - PL - PT - PY - PS - QA - RO - RS - SA - SE - SG - SI - SK - SV - TH - TN - TR - TW - UA - US - UY - VE - VN - ZA - AD - AF - AS - AZ - BB - BQ - CG - CI - CM - CW - DM - DZ - FO - GF - GP - JM - KG - KH - KI - KZ - LK - LR - LS - MW - NC - PG - TD - TF - UG - VU - ZW required: - field - operator - values - type: object properties: field: type: string enum: - chat_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - brand_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values having: description: >- 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. example: - field: brand_id operator: in values: - kw_abc123 type: array items: anyOf: - type: object properties: field: type: string enum: - model_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - chatgpt-scraper - gpt-4o - gpt-4o-search - gpt-3.5-turbo - llama-sonar - perplexity-scraper - sonar - gemini-2.5-flash - gemini-scraper - google-ai-overview-scraper - google-ai-mode-scraper - llama-3.3-70b-instruct - deepseek-r1 - deepseek-v4-pro - claude-3.5-haiku - claude-haiku-4.5 - claude-sonnet-4 - grok-scraper - microsoft-copilot-scraper - grok-4 - grok-4.3 - qwen-3-6-plus - qwen-3-7-plus - amazon-rufus-scraper required: - field - operator - values deprecated: true description: 'Deprecated: use model_channel_id filter instead' - type: object properties: field: type: string enum: - model_channel_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - openai-0 - openai-1 - qwen-0 - openai-2 - perplexity-0 - perplexity-1 - google-0 - google-1 - google-2 - google-3 - anthropic-0 - anthropic-1 - deepseek-0 - meta-0 - xai-0 - xai-1 - microsoft-0 - amazon-0 required: - field - operator - values - type: object properties: field: type: string enum: - tag_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - topic_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - prompt_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - country_code operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string enum: - AE - AL - AM - AR - AT - AU - BA - BE - BG - BH - BO - BR - BS - BY - CA - CH - CL - CN - CO - CR - CY - CZ - DE - DK - DO - EC - EE - EG - ES - FI - FR - GB - GE - GH - GR - GT - HK - HN - HR - HU - ID - IE - IL - IN - IQ - IS - IT - JO - JP - KR - KW - LB - LI - LT - LU - LV - MA - MD - ME - MK - MT - MX - MY - NG - NI - NL - 'NO' - NZ - OM - PK - PA - PE - PH - PL - PT - PY - PS - QA - RO - RS - SA - SE - SG - SI - SK - SV - TH - TN - TR - TW - UA - US - UY - VE - VN - ZA - AD - AF - AS - AZ - BB - BQ - CG - CI - CM - CW - DM - DZ - FO - GF - GP - JM - KG - KH - KI - KZ - LK - LR - LS - MW - NC - PG - TD - TF - UG - VU - ZW required: - field - operator - values - type: object properties: field: type: string enum: - chat_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values - type: object properties: field: type: string enum: - brand_id operator: type: string enum: - in - not_in values: minItems: 1 type: array items: type: string required: - field - operator - values order_by: description: >- 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. example: - field: visibility direction: desc type: array items: type: object properties: field: type: string enum: - visibility - visibility_count - mention_count - sentiment - position - share_of_voice - date - week - month direction: default: desc type: string enum: - asc - desc required: - field responses: '200': description: Success content: application/json: schema: type: object properties: data: type: array items: type: object properties: brand: type: object properties: id: type: string example: kw_915e742b-396d-4a86-ad57-8bc84e8c2232 name: type: string example: Peec AI required: - id - name prompt: type: object properties: id: type: string example: pr_93f790de-5b7a-45ee-b782-61103c81f20d required: - id model: deprecated: true description: 'Deprecated: use model_channel instead' type: object properties: id: type: string example: gpt-4o-search required: - id model_channel: type: object properties: id: type: string example: openai-1 required: - id tag: type: object properties: id: type: string example: tg_23abec5b-100a-4261-9ee7-1effe68f0149 required: - id topic: type: object properties: id: type: string example: to_e6b8cdd3-a51b-4d94-a866-28dbe6b830a6 required: - id country_code: example: US type: string chat: type: object properties: id: type: string example: ch_abc123 required: - id date: example: '2025-03-15' type: string week: example: '2025-03-10' description: Start (Monday) of the ISO week bucket. type: string month: example: '2025-03-01' description: First day of the month bucket. type: string share_of_voice: example: 0.15 description: >- 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]. type: number mention_count: type: number example: 42 visibility: type: number example: 0.5 visibility_count: type: number example: 5 visibility_total: type: number example: 10 sentiment: example: 50 type: number sentiment_sum: example: 0 type: number sentiment_count: type: number example: 10 position: example: 1.5 type: number position_sum: example: 15 type: number position_count: type: number example: 10 required: - brand - mention_count - visibility - visibility_count - visibility_total required: - data description: Success security: - APIKeyHeader: [] - APIKeyQuery: [] - BearerAuth: [] components: securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key APIKeyQuery: type: apiKey in: query name: api_key BearerAuth: type: http scheme: bearer bearerFormat: JWT ````