Skip to main content
GET
/
api
/
v1
/
brands
/
{brandId}
/
perception
Brand Perception
curl --request GET \
  --url https://api.example.com/api/v1/brands/{brandId}/perception \
  --header 'Authorization: <authorization>'
{
  "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>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt

Use this file to discover all available pages before exploring further.

Brand Perception tracks how AI models describe your brand over time. Each monthly snapshot carries four scores (0-100): sentiment, alignment (match with your positioning), consistency (agreement across AI providers) and factual alignment (accuracy against your known brand facts). This endpoint returns the latest snapshot, the previous one, month-over-month trends, averages and the full history — the same data shown on the dashboard Perception tab.
Perception snapshots are generated monthly. There is no day-based period filter — use months to control the history depth.
​
Authorization
string
required
Bearer token. Example: Bearer qw-api-xxx

​
Path Parameters

​
brandId
string
required
The unique identifier of the brand

​
Query Parameters

​
months
number
default:"12"
Number of months of history to include (max: 24). Only COMPLETED snapshots are returned.

​
Response

​
success
boolean
Indicates if the request was successful
​
brand
object
​
current
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).
​
previous
object
Previous completed snapshot in the same shape as current, or null.
​
trends
object
Difference (current − previous) for each score: sentiment, alignment, consistency, factualAlignment. A value is null when either side is missing.
​
averages
object
Average of each score across the returned history (null when no data points).
​
history
array
​
meta
object
months (requested window) and dataPoints (number of snapshots returned).
​
nextAnalysisDate
string
Estimated date of the next monthly snapshot (ISO 8601).

​
Example Request

curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/perception?months=6" \
  -H "Authorization: Bearer qw-api-your-token-here"

​
Example Response

{
  "success": true,
  "brand": {
    "id": "cm1234567890abcdef",
    "name": "My Brand",
    "domain": "mybrand.com"
  },
  "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"
}