Get Perception Snapshot

Full detail of a single perception snapshot: scores, attribute alignment and SWOT

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

Get Perception Snapshot

cURL

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

200

{
  "success": true,
  "brand": {},
  "snapshot": {
    "snapshotId": "<string>",
    "month": 123,
    "year": 123,
    "scores": {},
    "attributes": [
      {}
    ],
    "attributeMetrics": {},
    "insights": {},
    "providers": [
      {}
    ],
    "createdAt": "<string>",
    "completedAt": "<string>"
  }
}

Retrieve the full detail of a single completed perception snapshot: the four scores, the attribute alignment breakdown and the SWOT insights. Get a snapshotId from the Brand Perception endpoint’s history array.

Authorization · string · required

Bearer token. Example: Bearer qw-api-xxx

Path Parameters

brandId · string · required

The unique identifier of the brand

snapshotId · string · required

The unique identifier of the perception snapshot

Response

success · boolean

Indicates if the request was successful

brand · object

id, name, domain

snapshot · object

Show Snapshot

snapshotId · string

Snapshot ID

month · number

Month (1-12)

year · number

Year

scores · object

sentiment, alignment, consistency, factualAlignment (0-100 or null)

attributes · array

Brand attributes evaluated by AI. Each object has text (string) and status (aligned, partial, missing).

attributeMetrics · object

Counts: aligned, partial, missing, total.

insights · object

SWOT arrays of strings: strengths, weaknesses, opportunities, threats.

providers · array

AI providers included in the analysis

createdAt · string

Creation timestamp (ISO 8601)

completedAt · string

Completion timestamp (ISO 8601) or null

A 404 RESOURCE_NOT_FOUND is returned if the snapshot does not exist, is not COMPLETED, or does not belong to the brand.

Example Request

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

Example Response

{
  "success": true,
  "brand": {
    "id": "cm1234567890abcdef",
    "name": "My Brand",
    "domain": "mybrand.com"
  },
  "snapshot": {
    "snapshotId": "snap_2026_05",
    "month": 5,
    "year": 2026,
    "scores": {
      "sentiment": 78,
      "alignment": 65,
      "consistency": 82,
      "factualAlignment": 71
    },
    "attributes": [
      { "text": "Premium positioning", "status": "aligned" },
      { "text": "Sustainable materials", "status": "partial" },
      { "text": "Made in France", "status": "missing" }
    ],
    "attributeMetrics": {
      "aligned": 1,
      "partial": 1,
      "missing": 1,
      "total": 3
    },
    "insights": {
      "strengths": ["Strong brand recognition in core market"],
      "weaknesses": ["Limited awareness of product range"],
      "opportunities": ["Growing demand in adjacent category"],
      "threats": ["Aggressive competitor messaging"]
    },
    "providers": ["chatgpt", "perplexity"],
    "createdAt": "2026-05-01T03:00:00.000Z",
    "completedAt": "2026-05-03T04:12:00.000Z"
  }
}