Queries

A query is a question a shopper could ask an AI assistant — « best carbon gravel bike under €3,000 ». Skoup asks every enabled query of a market to every model, several times, at each weekly sampling, then reads which brands and products the answers recommend. The panel of queries is what the brand’s visibility is measured on.

A query belongs to one market and is written in that market’s language; there is no parent query translated per market. Only enabled queries are asked, and they count against the workspace’s query quota.

Statuses of a query

enableddisabled

Disabling a query frees a slot of the quota and stops measuring it from the next sampling; its history is kept. Enabling it again takes a slot.

I want to…

I want to…	Call
List the queries of a market, with their visibility	`GET /v1/brands/{brand}/queries?market=FR`
List only the enabled ones	`GET /v1/brands/{brand}/queries?enabled=true`
Read one query	`GET /v1/brands/{brand}/queries/{query}`
Add a query to the panel	`POST /v1/brands/{brand}/queries` (`text`, `market`, `category`)
Stop measuring a query	`PATCH /v1/brands/{brand}/queries/{query}` with `enabled: false`
Know how many slots are left	The `Skoup-Quota-Queries` header of any queries call

Scopes: queries:read, queries:write. Events: none of its own — the new measurements arrive with sampling.completed.

Scenario: push the questions your support team hears


curl -X POST https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/queries \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Idempotency-Key: support-faq-2026-09-23-12" \
  -H "Content-Type: application/json" \
  -d '{"text":"vélo gravel léger pour bikepacking","market":"FR","category":"Gravel"}'

The response carries Skoup-Quota-Queries: limit=150, remaining=37. The query is measured from the next weekly sampling.

Pitfalls

The quota counts enabled queries on all markets. When it is reached, creating or enabling a query answers 422 quota_exceeded; disable another one first.
The market must be activated on the brand, or the call answers 422 parameter_invalid on market.
A new query has no visibility yet: its visibility block stays empty until a sampling asked it.