Queries

Endpoints

POST/v1/brands/{brand}/queries
PATCH/v1/brands/{brand}/queries/{query}
GET/v1/brands/{brand}/queries/{query}
GET/v1/brands/{brand}/queries

The Query object

Attributes

idstring
Unique identifier of the object (prefixed, opaque).
objectstring
query
textstring
marketstring
Market code (ISO country, e.g. FR).
categorystringnullable
intentenum
The shopping-query templates of the spec: « meilleur X », « X vs Z », « alternatives à X ». Detected on manual prompts, explicit on generated ones; anything else is custom.
Possible values: best_x · x_vs_z · alternatives_to_x · custom
sourceenum
| | |---| | generated <br/> Generated from the catalog at onboarding / re-generation. | | manual <br/> Added by hand in the prompt panel. |
Possible values: generated · manual
enabledboolean
visibilityobject
Share (%) of the answers citing the brand over the period — null before any measurement.
livemodeboolean
true for live data, false for the test-mode sandbox.
createdinteger
Time at which the object was created (unix timestamp, seconds).

The Query object


{
  "id": "qry_034ONPxljEmTTql8cv7qJk",
  "object": "query",
  "text": "meilleur vélo gravel carbone à moins de 3000 €",
  "market": "FR",
  "category": "string",
  "intent": "best_x",
  "source": "generated",
  "enabled": true,
  "visibility": {},
  "livemode": true,
  "created": 1790000000
}

Create a query

POST/v1/brands/{brand}/queries

Adds a query to the panel of an activated market, enabled: it is asked from the next weekly sampling on. A duplicate on the market, or a full quota (quota_exceeded), answers 422.

Parameters

brandstringrequired
Brand id (br_…).
textstringrequired
marketstringrequired
An activated market of the brand (ISO 3166-1 alpha-2).
categorystringnullable

Returns

Returns the created query object. Raises an error if something goes wrong.

curl


curl -X POST https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"text":"meilleur vélo gravel carbone à moins de 3000 €","market":"FR","category":"string"}'

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"text":"meilleur vélo gravel carbone à moins de 3000 €","market":"FR","category":"string"}),
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('POST', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/queries', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
    'json' => ['text' => 'meilleur vélo gravel carbone à moins de 3000 €', 'market' => 'FR', 'category' => 'string'],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.post(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
    json={"text": "meilleur vélo gravel carbone à moins de 3000 €", "market": "FR", "category": "string"},
)
data = response.json()

Response


{
  "id": "qry_034ONPxljEmTTql8cv7qJk",
  "object": "query",
  "text": "meilleur vélo gravel carbone à moins de 3000 €",
  "market": "FR",
  "category": "string",
  "intent": "best_x",
  "source": "generated",
  "enabled": true,
  "visibility": {},
  "livemode": true,
  "created": 1790000000
}

Update a query

PATCH/v1/brands/{brand}/queries/{query}

Edits the text or the category, or enables / disables the query. Disabling frees a slot of the quota; enabling takes one.

Parameters

brandstringrequired
Brand id (br_…).
querystringrequired
Query id (qry_…).
textstring
categorystringnullable
enabledboolean

Returns

Returns the updated query object. Raises an error if something goes wrong.

curl


curl -X PATCH https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"text":"meilleur vélo gravel carbone à moins de 3000 €","category":"string"}'

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"text":"meilleur vélo gravel carbone à moins de 3000 €","category":"string"}),
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('PATCH', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
    'json' => ['text' => 'meilleur vélo gravel carbone à moins de 3000 €', 'category' => 'string'],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.patch(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
    json={"text": "meilleur vélo gravel carbone à moins de 3000 €", "category": "string"},
)
data = response.json()

Response


{
  "id": "qry_034ONPxljEmTTql8cv7qJk",
  "object": "query",
  "text": "meilleur vélo gravel carbone à moins de 3000 €",
  "market": "FR",
  "category": "string",
  "intent": "best_x",
  "source": "generated",
  "enabled": true,
  "visibility": {},
  "livemode": true,
  "created": 1790000000
}

Retrieve a query

GET/v1/brands/{brand}/queries/{query}

Parameters

brandstringrequired
Brand id (br_…).
querystringrequired
Query id (qry_…).

Returns

Returns the query object. Raises an error if something goes wrong.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries/qry_034ONPxljEmTTql8cv7qJk",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "id": "qry_034ONPxljEmTTql8cv7qJk",
  "object": "query",
  "text": "meilleur vélo gravel carbone à moins de 3000 €",
  "market": "FR",
  "category": "string",
  "intent": "best_x",
  "source": "generated",
  "enabled": true,
  "visibility": {},
  "livemode": true,
  "created": 1790000000
}

List queries

GET/v1/brands/{brand}/queries

The queries of the brand’s panel — the questions asked to the AI models every week — with the share of the answers citing the brand over the period.

Parameters

brandstringrequired
Brand id (br_…).
marketstring
enabledstring
limitinteger
Number of objects to return, between 1 and 100 (default 20).
starting_afterstring
Cursor: the id of the last object of the previous page.

Returns

A dictionary with a data property holding up to limit query objects, newest first, and has_more telling whether another page exists. Raises an error if something goes wrong.

curl


curl https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries?limit=3', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.SKOUP_API_KEY}`,
  },
})
const data = await response.json()

PHP


$client = new GuzzleHttp\Client(['base_uri' => 'https://api.skoup.ai/v1/']);
$response = $client->request('GET', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/queries?limit=3', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


import os, requests
 
response = requests.get(
    "https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries?limit=3",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "object": "list",
  "url": "/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/queries",
  "has_more": false,
  "data": [
    {
      "id": "qry_034ONPxljEmTTql8cv7qJk",
      "object": "query",
      "text": "meilleur vélo gravel carbone à moins de 3000 €",
      "market": "FR",
      "category": "string",
      "intent": "best_x",
      "source": "generated",
      "enabled": true,
      "visibility": {},
      "livemode": true,
      "created": 1790000000
    }
  ]
}