Alerts

Related events: alert.created · alert.resolved · alert.updated

Endpoints

GET/v1/brands/{brand}/alerts/{alert}
GET/v1/brands/{brand}/alerts
POST/v1/brands/{brand}/alerts/{alert}/dismiss
POST/v1/brands/{brand}/alerts/{alert}/treat
POST/v1/brands/{brand}/alerts/{alert}/verify

The Alert object

Attributes

idstring
Unique identifier of the object (prefixed, opaque).
objectstring
alert
brandstring
The brand the object belongs to (br_…).
marketstring
Market code (ISO country, e.g. FR).
kindenum
What an alert reports. Adding a kind = one case here, one detector and the copy; the inbox is data-driven.
Possible values: price_hallucination · wrong_availability · visibility_drop · new_competitor · spec_invented · wrong_local_fact · seo_regression
severityenum
Possible values: critical · medium · low
statusenum
Lifecycle of an alert (mockup): Nouvelle → Vue → Traitée → Résolue vérifiée, plus Ignorée on the side. Resolved is only ever reached by a verification re-sampling (ResolveVerifiedAlerts), never by the API.
Possible values: new · seen · treated · resolved · ignored
productobjectnullable
Show child attributes
- idstringnullable
  Unique identifier of the object (prefixed, opaque).
- titlestring
queryobjectnullable
Show child attributes
- idstringnullable
  Unique identifier of the object (prefixed, opaque).
- textstring
competitorstringnullable
locationobjectnullable
Show child attributes
- idstring
  Unique identifier of the object (prefixed, opaque).
- namestringnullable
- citystringnullable
modelenumnullable
The AI assistants Skoup samples. Keys match the front's lib/ai-models.ts and the --model-* tokens; model ids and providers live in config('skoup.visibility').
Possible values: chatgpt · claude · gemini · perplexity · grok · mistral · deepseek · qwen
modelsarray of object
Show child attributes
- modelstring
- occurrencesinteger
occurrencesinteger
claimedobject
truthobjectnullable
persistedboolean
The claim survived the last verification re-sampling.
verificationsinteger
first_seen_atstring
last_seen_atstring
treated_atstringnullable
dismissed_atstringnullable
close_reasonenumnullable
Why Skoup itself closed an alert. Rejudged: the way a claim is judged changed and this one no longer counts as wrong — never a fix the brand made, so never « resolved ».
Possible values: rejudged
last_verification_atstringnullable
resolved_atstringnullable
livemodeboolean
true for live data, false for the test-mode sandbox.
createdinteger
Time at which the object was created (unix timestamp, seconds).

The Alert object


{
  "id": "alrt_031CQlTxUKUOFYaHSd3kBY",
  "object": "alert",
  "brand": "br_031CQGx2DNM4mxT2CO7BL3",
  "market": "FR",
  "kind": "price_hallucination",
  "severity": "critical",
  "status": "new",
  "product": {
    "id": "prod_031CQNg2fZXIIClKM3I8uF",
    "title": "Grizl CF SL 7"
  },
  "query": {
    "id": "qry_031CQSmQyxphdXPSkx2QxP",
    "text": "meilleur vélo gravel carbone à moins de 3000 €"
  },
  "competitor": null,
  "model": "chatgpt",
  "models": [
    {
      "model": "chatgpt",
      "occurrences": 2
    },
    {
      "model": "gemini",
      "occurrences": 1
    }
  ],
  "occurrences": 3,
  "claimed": {
    "price": 2199,
    "price_max": null,
    "price_kind": "exact",
    "period": null,
    "unit": null,
    "scope": "offer",
    "currency": "EUR",
    "min": 2199,
    "max": 2199,
    "gap": 0.12,
    "runs": 3
  },
  "truth": {
    "price": 2499,
    "min": 2499,
    "max": 2499,
    "currency": "EUR",
    "period": null,
    "unit": null,
    "annual_min": null,
    "annual_max": null,
    "max_with_addons": 2499,
    "open_ended": false,
    "addons": [],
    "scope": "offer",
    "variants": 4,
    "checked_at": "2026-09-21T02:40:00Z"
  },
  "persisted": false,
  "verifications": 0,
  "first_seen_at": "2026-09-21T02:40:00Z",
  "last_seen_at": "2026-09-21T02:40:00Z",
  "treated_at": null,
  "dismissed_at": null,
  "close_reason": null,
  "last_verification_at": null,
  "resolved_at": null,
  "livemode": true,
  "created": 1790000000
}

Retrieve an alert

GET/v1/brands/{brand}/alerts/{alert}

Parameters

brandstringrequired
Brand id (br_…).
alertstringrequired
Alert id (alrt_…).

Returns

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

curl


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

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/alerts/alrt_034sOvSY3W2DUqG0hp23SH', {
  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/alerts/alrt_034sOvSY3W2DUqG0hp23SH', [
    '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/alerts/alrt_034sOvSY3W2DUqG0hp23SH",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "id": "alrt_031CQlTxUKUOFYaHSd3kBY",
  "object": "alert",
  "brand": "br_031CQGx2DNM4mxT2CO7BL3",
  "market": "FR",
  "kind": "price_hallucination",
  "severity": "critical",
  "status": "new",
  "product": {
    "id": "prod_031CQNg2fZXIIClKM3I8uF",
    "title": "Grizl CF SL 7"
  },
  "query": {
    "id": "qry_031CQSmQyxphdXPSkx2QxP",
    "text": "meilleur vélo gravel carbone à moins de 3000 €"
  },
  "competitor": null,
  "model": "chatgpt",
  "models": [
    {
      "model": "chatgpt",
      "occurrences": 2
    },
    {
      "model": "gemini",
      "occurrences": 1
    }
  ],
  "occurrences": 3,
  "claimed": {
    "price": 2199,
    "price_max": null,
    "price_kind": "exact",
    "period": null,
    "unit": null,
    "scope": "offer",
    "currency": "EUR",
    "min": 2199,
    "max": 2199,
    "gap": 0.12,
    "runs": 3
  },
  "truth": {
    "price": 2499,
    "min": 2499,
    "max": 2499,
    "currency": "EUR",
    "period": null,
    "unit": null,
    "annual_min": null,
    "annual_max": null,
    "max_with_addons": 2499,
    "open_ended": false,
    "addons": [],
    "scope": "offer",
    "variants": 4,
    "checked_at": "2026-09-21T02:40:00Z"
  },
  "persisted": false,
  "verifications": 0,
  "first_seen_at": "2026-09-21T02:40:00Z",
  "last_seen_at": "2026-09-21T02:40:00Z",
  "treated_at": null,
  "dismissed_at": null,
  "close_reason": null,
  "last_verification_at": null,
  "resolved_at": null,
  "livemode": true,
  "created": 1790000000
}

List alerts

GET/v1/brands/{brand}/alerts

Incidents detected at the end of the samplings — price hallucinations, wrong availability, visibility drops, new competitors, invented specs — newest first.

Parameters

brandstringrequired
Brand id (br_…).
marketstring
statusstring
kindstring
severitystring
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 alert 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/alerts?limit=3 \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/alerts?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/alerts?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/alerts?limit=3",
    headers={"Authorization": f"Bearer {os.environ['SKOUP_API_KEY']}"},
)
data = response.json()

Response


{
  "object": "list",
  "url": "/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/alerts",
  "has_more": false,
  "data": [
    {
      "id": "alrt_031CQlTxUKUOFYaHSd3kBY",
      "object": "alert",
      "brand": "br_031CQGx2DNM4mxT2CO7BL3",
      "market": "FR",
      "kind": "price_hallucination",
      "severity": "critical",
      "status": "new",
      "product": {
        "id": "prod_031CQNg2fZXIIClKM3I8uF",
        "title": "Grizl CF SL 7"
      },
      "query": {
        "id": "qry_031CQSmQyxphdXPSkx2QxP",
        "text": "meilleur vélo gravel carbone à moins de 3000 €"
      },
      "competitor": null,
      "model": "chatgpt",
      "models": [
        {
          "model": "chatgpt",
          "occurrences": 2
        },
        {
          "model": "gemini",
          "occurrences": 1
        }
      ],
      "occurrences": 3,
      "claimed": {
        "price": 2199,
        "price_max": null,
        "price_kind": "exact",
        "period": null,
        "unit": null,
        "scope": "offer",
        "currency": "EUR",
        "min": 2199,
        "max": 2199,
        "gap": 0.12,
        "runs": 3
      },
      "truth": {
        "price": 2499,
        "min": 2499,
        "max": 2499,
        "currency": "EUR",
        "period": null,
        "unit": null,
        "annual_min": null,
        "annual_max": null,
        "max_with_addons": 2499,
        "open_ended": false,
        "addons": [],
        "scope": "offer",
        "variants": 4,
        "checked_at": "2026-09-21T02:40:00Z"
      },
      "persisted": false,
      "verifications": 0,
      "first_seen_at": "2026-09-21T02:40:00Z",
      "last_seen_at": "2026-09-21T02:40:00Z",
      "treated_at": null,
      "dismissed_at": null,
      "close_reason": null,
      "last_verification_at": null,
      "resolved_at": null,
      "livemode": true,
      "created": 1790000000
    }
  ]
}

Dismiss an alert

POST/v1/brands/{brand}/alerts/{alert}/dismiss

Ignores the alert. If the incident happens again, a new alert opens.

Parameters

brandstringrequired
Brand id (br_…).
alertstringrequired
Alert id (alrt_…).

Returns

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

curl


curl -X POST https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/alerts/alrt_034sOvSY3W2DUqG0hp23SH/dismiss \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/alerts/alrt_034sOvSY3W2DUqG0hp23SH/dismiss', {
  method: 'POST',
  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('POST', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/alerts/alrt_034sOvSY3W2DUqG0hp23SH/dismiss', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


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

Response


{
  "id": "alrt_031CQlTxUKUOFYaHSd3kBY",
  "object": "alert",
  "brand": "br_031CQGx2DNM4mxT2CO7BL3",
  "market": "FR",
  "kind": "price_hallucination",
  "severity": "critical",
  "status": "new",
  "product": {
    "id": "prod_031CQNg2fZXIIClKM3I8uF",
    "title": "Grizl CF SL 7"
  },
  "query": {
    "id": "qry_031CQSmQyxphdXPSkx2QxP",
    "text": "meilleur vélo gravel carbone à moins de 3000 €"
  },
  "competitor": null,
  "model": "chatgpt",
  "models": [
    {
      "model": "chatgpt",
      "occurrences": 2
    },
    {
      "model": "gemini",
      "occurrences": 1
    }
  ],
  "occurrences": 3,
  "claimed": {
    "price": 2199,
    "price_max": null,
    "price_kind": "exact",
    "period": null,
    "unit": null,
    "scope": "offer",
    "currency": "EUR",
    "min": 2199,
    "max": 2199,
    "gap": 0.12,
    "runs": 3
  },
  "truth": {
    "price": 2499,
    "min": 2499,
    "max": 2499,
    "currency": "EUR",
    "period": null,
    "unit": null,
    "annual_min": null,
    "annual_max": null,
    "max_with_addons": 2499,
    "open_ended": false,
    "addons": [],
    "scope": "offer",
    "variants": 4,
    "checked_at": "2026-09-21T02:40:00Z"
  },
  "persisted": false,
  "verifications": 0,
  "first_seen_at": "2026-09-21T02:40:00Z",
  "last_seen_at": "2026-09-21T02:40:00Z",
  "treated_at": null,
  "dismissed_at": null,
  "close_reason": null,
  "last_verification_at": null,
  "resolved_at": null,
  "livemode": true,
  "created": 1790000000
}

Treat an alert

POST/v1/brands/{brand}/alerts/{alert}/treat

Marks the alert as treated — the fix was made. Verify it next to close it for good.

Parameters

brandstringrequired
Brand id (br_…).
alertstringrequired
Alert id (alrt_…).

Returns

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

curl


curl -X POST https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/alerts/alrt_034sOvSY3W2DUqG0hp23SH/treat \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/alerts/alrt_034sOvSY3W2DUqG0hp23SH/treat', {
  method: 'POST',
  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('POST', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/alerts/alrt_034sOvSY3W2DUqG0hp23SH/treat', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


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

Response


{
  "id": "alrt_031CQlTxUKUOFYaHSd3kBY",
  "object": "alert",
  "brand": "br_031CQGx2DNM4mxT2CO7BL3",
  "market": "FR",
  "kind": "price_hallucination",
  "severity": "critical",
  "status": "new",
  "product": {
    "id": "prod_031CQNg2fZXIIClKM3I8uF",
    "title": "Grizl CF SL 7"
  },
  "query": {
    "id": "qry_031CQSmQyxphdXPSkx2QxP",
    "text": "meilleur vélo gravel carbone à moins de 3000 €"
  },
  "competitor": null,
  "model": "chatgpt",
  "models": [
    {
      "model": "chatgpt",
      "occurrences": 2
    },
    {
      "model": "gemini",
      "occurrences": 1
    }
  ],
  "occurrences": 3,
  "claimed": {
    "price": 2199,
    "price_max": null,
    "price_kind": "exact",
    "period": null,
    "unit": null,
    "scope": "offer",
    "currency": "EUR",
    "min": 2199,
    "max": 2199,
    "gap": 0.12,
    "runs": 3
  },
  "truth": {
    "price": 2499,
    "min": 2499,
    "max": 2499,
    "currency": "EUR",
    "period": null,
    "unit": null,
    "annual_min": null,
    "annual_max": null,
    "max_with_addons": 2499,
    "open_ended": false,
    "addons": [],
    "scope": "offer",
    "variants": 4,
    "checked_at": "2026-09-21T02:40:00Z"
  },
  "persisted": false,
  "verifications": 0,
  "first_seen_at": "2026-09-21T02:40:00Z",
  "last_seen_at": "2026-09-21T02:40:00Z",
  "treated_at": null,
  "dismissed_at": null,
  "close_reason": null,
  "last_verification_at": null,
  "resolved_at": null,
  "livemode": true,
  "created": 1790000000
}

Verify an alert

POST/v1/brands/{brand}/alerts/{alert}/verify

Re-samples the alert’s query on every model to check the fix. The alert must be treated. Answers 202 when a verification starts, 200 when one already in flight is reused; the verdict arrives later as alert.resolved (or alert.updated with persisted: true). Re-samplings are capped per brand and per day — see the Skoup-Quota-Verifications header.

Parameters

brandstringrequired
Brand id (br_…).
alertstringrequired
Alert id (alrt_…).

Returns

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

curl


curl -X POST https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/alerts/alrt_034sOvSY3W2DUqG0hp23SH/verify \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Node.js


const response = await fetch('https://api.skoup.ai/v1/brands/br_034CyfRFSXUqzrbzV6MAfZ/alerts/alrt_034sOvSY3W2DUqG0hp23SH/verify', {
  method: 'POST',
  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('POST', 'brands/br_034CyfRFSXUqzrbzV6MAfZ/alerts/alrt_034sOvSY3W2DUqG0hp23SH/verify', [
    'headers' => ['Authorization' => 'Bearer '.getenv('SKOUP_API_KEY')],
]);
$data = json_decode((string) $response->getBody(), true);

Python


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

Response


{
  "id": "alrt_031CQlTxUKUOFYaHSd3kBY",
  "object": "alert",
  "brand": "br_031CQGx2DNM4mxT2CO7BL3",
  "market": "FR",
  "kind": "price_hallucination",
  "severity": "critical",
  "status": "new",
  "product": {
    "id": "prod_031CQNg2fZXIIClKM3I8uF",
    "title": "Grizl CF SL 7"
  },
  "query": {
    "id": "qry_031CQSmQyxphdXPSkx2QxP",
    "text": "meilleur vélo gravel carbone à moins de 3000 €"
  },
  "competitor": null,
  "model": "chatgpt",
  "models": [
    {
      "model": "chatgpt",
      "occurrences": 2
    },
    {
      "model": "gemini",
      "occurrences": 1
    }
  ],
  "occurrences": 3,
  "claimed": {
    "price": 2199,
    "price_max": null,
    "price_kind": "exact",
    "period": null,
    "unit": null,
    "scope": "offer",
    "currency": "EUR",
    "min": 2199,
    "max": 2199,
    "gap": 0.12,
    "runs": 3
  },
  "truth": {
    "price": 2499,
    "min": 2499,
    "max": 2499,
    "currency": "EUR",
    "period": null,
    "unit": null,
    "annual_min": null,
    "annual_max": null,
    "max_with_addons": 2499,
    "open_ended": false,
    "addons": [],
    "scope": "offer",
    "variants": 4,
    "checked_at": "2026-09-21T02:40:00Z"
  },
  "persisted": false,
  "verifications": 0,
  "first_seen_at": "2026-09-21T02:40:00Z",
  "last_seen_at": "2026-09-21T02:40:00Z",
  "treated_at": null,
  "dismissed_at": null,
  "close_reason": null,
  "last_verification_at": null,
  "resolved_at": null,
  "livemode": true,
  "created": 1790000000
}