> ## 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

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

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.

<Note>
  Perception snapshots are generated monthly. There is no day-based `period` filter — use `months` to control the history depth.
</Note>

<ParamField header="Authorization" type="string" required>
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

### Path Parameters

<ParamField path="brandId" type="string" required>
  The unique identifier of the brand
</ParamField>

### Query Parameters

<ParamField query="months" type="number" default="12">
  Number of months of history to include (max: 24). Only `COMPLETED` snapshots are returned.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="brand" type="object">
  <Expandable title="Brand">
    <ResponseField name="id" type="string">Brand ID</ResponseField>
    <ResponseField name="name" type="string">Brand name</ResponseField>
    <ResponseField name="domain" type="string">Brand domain</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="current" type="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`).
</ResponseField>

<ResponseField name="previous" type="object">
  Previous completed snapshot in the same shape as `current`, or `null`.
</ResponseField>

<ResponseField name="trends" type="object">
  Difference (current − previous) for each score: `sentiment`, `alignment`, `consistency`, `factualAlignment`. A value is `null` when either side is missing.
</ResponseField>

<ResponseField name="averages" type="object">
  Average of each score across the returned history (`null` when no data points).
</ResponseField>

<ResponseField name="history" type="array">
  <Expandable title="History point">
    <ResponseField name="snapshotId" type="string">Snapshot ID (use with the detail endpoint)</ResponseField>
    <ResponseField name="month" type="number">Month (1-12)</ResponseField>
    <ResponseField name="year" type="number">Year</ResponseField>
    <ResponseField name="label" type="string">`MM/YYYY` label</ResponseField>
    <ResponseField name="scores" type="object">`sentiment`, `alignment`, `consistency`, `factualAlignment`</ResponseField>
    <ResponseField name="completedAt" type="string">Completion timestamp (ISO 8601) or `null`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  `months` (requested window) and `dataPoints` (number of snapshots returned).
</ResponseField>

<ResponseField name="nextAnalysisDate" type="string">
  Estimated date of the next monthly snapshot (ISO 8601).
</ResponseField>

### Example Request

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

### Example Response

```json theme={null}
{
  "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"
}
```