List perception snapshots
curl --request GET \
--url https://www.qwairy.co/api/v1/brands/{brandId}/perception \
--header 'Authorization: <authorization>'import requests
url = "https://www.qwairy.co/api/v1/brands/{brandId}/perception"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://www.qwairy.co/api/v1/brands/{brandId}/perception', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"brand": {
"id": "<string>",
"name": "<string>",
"domain": "<string>"
},
"current": {},
"previous": {},
"trends": {},
"averages": {},
"history": [
{
"snapshotId": "<string>",
"month": 123,
"year": 123,
"label": "<string>",
"scores": {},
"completedAt": "<string>"
}
],
"meta": {},
"nextAnalysisDate": "<string>"
}Perception
List perception snapshots
List completed monthly perception snapshots with scores, trends, averages, and history.
GET
https://www.qwairy.co
/
api
/
v1
/
brands
/
{brandId}
/
perception
List perception snapshots
curl --request GET \
--url https://www.qwairy.co/api/v1/brands/{brandId}/perception \
--header 'Authorization: <authorization>'import requests
url = "https://www.qwairy.co/api/v1/brands/{brandId}/perception"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://www.qwairy.co/api/v1/brands/{brandId}/perception', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"brand": {
"id": "<string>",
"name": "<string>",
"domain": "<string>"
},
"current": {},
"previous": {},
"trends": {},
"averages": {},
"history": [
{
"snapshotId": "<string>",
"month": 123,
"year": 123,
"label": "<string>",
"scores": {},
"completedAt": "<string>"
}
],
"meta": {},
"nextAnalysisDate": "<string>"
}Returns completed perception snapshots stored by month. Each snapshot can contain four
0-100 scores: sentiment, alignment, consistency, and factual alignment. A score can be null when it was not calculated.
There is no day-based
period filter. Use months to control the history depth. nextAnalysisDate is derived from the latest snapshot month; it is not a delivery guarantee.string
required
Bearer token. Example:
Bearer qw-api-xxxPath parameters
string
required
The unique identifier of the brand
Query parameters
number
default:"12"
Number of months of history to include (max: 24). Only
COMPLETED snapshots are returned.Response
boolean
Indicates if the request was successful
object
Latest completed snapshot, or
null if none. Contains snapshotId, month, year, completedAt, and a scores object with sentiment, alignment, consistency, factualAlignment (each 0-100 or null).object
Previous completed snapshot in the same shape as
current, or null.object
Difference (current − previous) for each score:
sentiment, alignment, consistency, factualAlignment. A value is null when either side is missing.object
Average of each score across the returned history (
null when no data points).array
object
months (requested window) and dataPoints (number of snapshots returned).string
First day of the month after the latest snapshot, or the next calendar month when no snapshot exists. This is a computed ISO 8601 date, not a completion promise.
Synthetic request
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/perception?months=6" \
-H "Authorization: Bearer qw-api-your-token-here"
Synthetic response
{
"success": true,
"brand": {
"id": "cm1234567890abcdef",
"name": "Northstar Labs",
"domain": "northstar.example"
},
"current": {
"snapshotId": "snap_2026_05",
"month": 5,
"year": 2026,
"scores": {
"sentiment": 78,
"alignment": 65,
"consistency": 82,
"factualAlignment": 71
},
"completedAt": "2026-05-03T04:12:00.000Z"
},
"previous": {
"snapshotId": "snap_2026_04",
"month": 4,
"year": 2026,
"scores": {
"sentiment": 74,
"alignment": 61,
"consistency": 80,
"factualAlignment": 69
},
"completedAt": "2026-04-02T04:09:00.000Z"
},
"trends": {
"sentiment": 4,
"alignment": 4,
"consistency": 2,
"factualAlignment": 2
},
"averages": {
"sentiment": 75.5,
"alignment": 62.0,
"consistency": 80.3,
"factualAlignment": 69.8
},
"history": [
{
"snapshotId": "snap_2026_04",
"month": 4,
"year": 2026,
"label": "04/2026",
"scores": {
"sentiment": 74,
"alignment": 61,
"consistency": 80,
"factualAlignment": 69
},
"completedAt": "2026-04-02T04:09:00.000Z"
},
{
"snapshotId": "snap_2026_05",
"month": 5,
"year": 2026,
"label": "05/2026",
"scores": {
"sentiment": 78,
"alignment": 65,
"consistency": 82,
"factualAlignment": 71
},
"completedAt": "2026-05-03T04:12:00.000Z"
}
],
"meta": {
"months": 6,
"dataPoints": 2
},
"nextAnalysisDate": "2026-06-01T00:00:00.000Z"
}
Errors
| Status | Code | Description |
|---|---|---|
400 | INVALID_PARAMETER | Invalid months value |
401 | gateway error | Authentication failed |
404 | BRAND_NOT_FOUND | Brand not found or not accessible |
429 | gateway error | Rate limit exceeded; honor Retry-After |