Skip to main content
GET
/
{brand_id}
/
query
Query
curl --request GET \
  --url https://api.scrunchai.com/v1/{brand_id}/query \
  --header 'Authorization: Bearer <token>'
[
  {
    "date": "20250115",
    "ai_platform": "ChatGPT",
    "brand_presence_percentage": 0.85
  },
  {
    "date": "20250115",
    "ai_platform": "Claude",
    "brand_presence_percentage": 0.72
  }
]

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
brand_id
integer
required

Query Parameters

​
start_date
string<date> | null

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

Example:

"2025-01-01"

​
end_date
string<date> | null

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

Example:

"2025-01-31"

​
limit
integer
default:50000

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

Required range: 1 <= x <= 90000
​
offset
integer
default:0

Number of rows to skip for pagination.

Required range: x >= 0
​
fields
string | null

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)
  • 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)

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)

Example: fields=date,ai_platform,brand_presence_percentage Comma-separated list of dimensions and metrics to return

Example:

"date,ai_platform,brand_presence_percentage"

Response

Array of query results with the requested dimensions and metrics

​
date
string

Daily timestamp in YYYYMMDD format

Example:

"20250115"

​
date_week
string

ISO week in YYYYWW format

Example:

"202503"

​
date_month
string

Month in YYYYMM format

Example:

"202501"

​
date_quarter
string

Quarter in YYYYQ# format

Example:

"2025Q1"

​
date_year
string

Year in YYYY format

Example:

"2025"

​
prompt_id
integer

Prompt identifier

​
prompt
string

Prompt text

​
persona_id
integer

Persona identifier

​
persona_name
string

Persona name

​
ai_platform
string

AI platform name (mapped display name)

Example:

"ChatGPT"

​
ai_platform_search_enabled
boolean

Whether search mode is enabled for the platform

​
tag
string

Prompt tag

​
source_url
string

Citation URL

​
source_type
enum<string>

Citation type

Available options:
brand,
competitor,
other
​
competitor_id
integer

Competitor identifier

​
competitor_name
string

Competitor name

​
branded
boolean

Whether the prompt is branded

​
stage
string

Journey stage display name

​
prompt_topic
string

Topic name

​
country
string

Geography as country code

​
responses
integer

Total response count (COUNT of distinct observations)

​
brand_presence_percentage
number<float>

Brand mention rate as a percentage (0-1 scale)

Example:

0.85

​
brand_position_score
number<float>

Brand positioning score (0-100 scale: top=100, middle=50, bottom=0)

Example:

75.5

​
brand_sentiment_score
number<float>

Brand sentiment score (0-100 scale: positive=100, mixed=50, negative=0)

Example:

82.3

​
competitor_presence_percentage
number<float>

Competitor mention rate as a percentage (0-1 scale)

Example:

0.65

​
competitor_position_score
number<float>

Competitor positioning score (0-100 scale)

Example:

60

​
competitor_sentiment_score
number<float>

Competitor sentiment score (0-100 scale)

Example:

55