Brand Perception

Monthly perception scores: sentiment, alignment, consistency and factual alignment

GET /api/v1/brands/{brandId}/perception

Brand Perception

cURL

curl --request GET \
  --url https://api.example.com/api/v1/brands/{brandId}/perception \
  --header 'Authorization: <authorization>'

200

{
  "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>"
}

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

Show Brand

id · string

Brand ID

name · string

Brand name

domain · string

Brand domain

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

Show History point

snapshotId · string

Snapshot ID (use with the detail endpoint)

month · number

Month (1-12)

year · number

Year

label · string

MM/YYYY label

scores · object

sentiment, alignment, consistency, factualAlignment

completedAt · string

Completion timestamp (ISO 8601) or null

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"
}