---
title: "Query"
method: GET
path: "/{brand_id}/query"
---

# Query

`GET /{brand_id}/query`

Query the data API to retrieve aggregated observation data across multiple dimensions and metrics. This endpoint dynamically generates SQL queries based on the requested fields, allowing flexible aggregation for analytics and reporting workflows.

The query endpoint returns pre-aggregated metrics grouped by the specified dimensions. Results are optimized for BI tools, reporting pipelines, and dashboards.

## Path parameters

- `brand_id` integer, required

## Query parameters

- `start_date` string, nullable — Start date for the query range (inclusive). Format: YYYY-MM-DD. Defaults to 30 days ago.
- `end_date` string, nullable — End date for the query range (inclusive). Format: YYYY-MM-DD. Defaults to today.
- `limit` integer — Maximum number of rows to return. Use with offset for pagination.
- `offset` integer — Number of rows to skip for pagination.
- `fields` string, nullable — Comma-separated list of dimensions and/or metrics to include in the query results. If omitted, all dimensions are returned. **Supported Dimensions:** - `date` - Daily timestamp (YYYYMMDD) - `date_week` - ISO week (YYYYWW) - `date_month` - Month (YYYYMM) - `date_quarter` - Quarter (YYYYQ#) - `date_year` - Year (YYYY) - `prompt_id` - Prompt ID (Integer) - `prompt` - Prompt text (String) - `persona_id` - Persona ID (Integer) - `persona_name` - Persona name (String) - `ai_platform` - AI platform name (String, mapped) - `ai_platform_search_enabled` - Search mode enabled (Boolean) - `tag` - Prompt tag (String) - `source_url` - Citation URL (String) - `source_type` - Citation type (brand, competitor, other) - `source_domain` - Citation host (String, www-stripped) - `competitor_id` - Competitor ID (Integer) - `competitor_name` - Competitor name (String) - `branded` - Branded prompt (Boolean) - `stage` - Journey stage (Display name) - `prompt_topic` - Topic name (String) - `country` - Geography (Country code) - `position_bucket` - Brand position bucket (top/middle/bottom) - `sentiment_band` - Brand sentiment band (positive/mixed/negative/none) **Supported Metrics:** - `responses` - Total responses (COUNT of distinct observations) - `brand_presence_percentage` - Brand mention rate (0-1 scale) - `brand_position_score` - Brand positioning (0-100 scale: top=100, middle=50, bottom=0) - `brand_sentiment_score` - Brand sentiment (0-100 scale: positive=100, mixed=50, negative=0) - `competitor_presence_percentage` - Competitor mention rate (0-1 scale) - `competitor_position_score` - Competitor positioning (0-100 scale) - `competitor_sentiment_score` - Competitor sentiment (0-100 scale) - `brand_citation_rate` / `competitor_citation_rate` - Share of responses citing an entity-owned source (0-1) - `brand_citation_share_of_voice` / `competitor_citation_share_of_voice` - Of responses that cite anything, share that cite an entity-owned source (0-1) - `citation_count` - Total citation occurrences across responses - `citation_unique_responses` - Distinct responses with at least one citation - `citation_unique_domains` - Distinct citation hosts (www-stripped) - `citation_unique_response_domains` - Distinct (response, domain, owner) triples; the legacy Citations page's composition grain. Group it by `owner` or `domain` (or any response-grain dimension). Grouping by `source_url` puts the URL back in the key and inflates the total by ~30-37%; `citation_segment` can place one triple in two segments **Example:** `fields=date,ai_platform,brand_presence_percentage`
- `filters` string[], nullable — Filter rows by dimension values **before** aggregation. Each filter uses the format `field:value`. Multiple values are joined with `|` for an IN match (e.g. `ai_platform:ChatGPT|Claude`). Prefix the value with `!` for negation (e.g. `branded:!true`). The `filters` parameter can be repeated to apply multiple filters; they are combined with AND. Filterable dimensions: `prompt_id`, `persona_id`, `persona_name`, `ai_platform`, `ai_platform_search_enabled`, `tag`, `competitor_id`, `competitor_name`, `branded`, `stage`, `prompt_topic`, `country`, `position_bucket`, `sentiment_band`, `date`, `date_week`, `date_month`, `date_quarter`, `date_year`. **Example:** `filters=ai_platform:ChatGPT&filters=branded:true`
- `having` string[], nullable — Filter **aggregated** metric values after GROUP BY. Each entry uses `metric:operator:value` format. **Operators:** `gt`, `gte`, `lt`, `lte`, `eq`, `neq`. **Example:** `having=brand_presence_percentage:gt:0&having=responses:gte:10`

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/scrunchai/apis/scrunch-data-api.md) · [All operations](https://skmtc.net/scrunchai/apis/scrunch-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scrunchai/scrunch-data-api/revisions/c4fe20c603a3/schema)