SCscrunchai

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.

get/{brand_id}/query

Request

  • Base URL
    https://api.scrunchai.com/v1
  • Auth
    HTTP bearer

Path parameters

brand_idinteger required

Query parameters

start_datestring nullable

Start date for the query range (inclusive). Format: YYYY-MM-DD. Defaults to 30 days ago.

end_datestring nullable

End date for the query range (inclusive). Format: YYYY-MM-DD. Defaults to today.

limitinteger

Maximum number of rows to return. Use with offset for pagination.

offsetinteger

Number of rows to skip for pagination.

fieldsstring 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)
  • owner - Cited-source owner (brand, competitor, other); citation metrics only as a breakdown
  • 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)
  • language - Declared prompt-variant language (ISO 639-1 code, not detected from the response)
  • 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

filtersstring[] 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, language, position_bucket, sentiment_band, date, date_week, date_month, date_quarter, date_year; citation-source filters owner (brand / competitor / other), domain, source_url, source_type.

owner keeps whole responses that cite at least one source of that owner; with a domain or source_url breakdown it keeps only the matching sources.

A prompt can carry several tags and topics. Filtering tag or prompt_topic while grouping by the same dimension returns rows only for the filtered values, not for the other tags or topics those prompts also carry.

Example: filters=ai_platform:ChatGPT&filters=branded:true

havingstring[] 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

Successful Response

unknown required

Changes

No recorded changes to this operation across all 31 revisions of this API.