Brand Perception

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

import requests

url = "https://api.example.com/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://api.example.com/api/v1/brands/{brandId}/perception', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/brands/{brandId}/perception",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/brands/{brandId}/perception"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/brands/{brandId}/perception")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

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

GET

api

brands

{brandId}

perception

Brand Perception

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

import requests

url = "https://api.example.com/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://api.example.com/api/v1/brands/{brandId}/perception', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/brands/{brandId}/perception",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/brands/{brandId}/perception"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/brands/{brandId}/perception")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

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

string

required

Bearer token. Example: Bearer qw-api-xxx

Path 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

Show Brand

string

Brand ID

string

Brand name

string

Brand domain

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

Show History point

string

Snapshot ID (use with the detail endpoint)

number

Month (1-12)

number

Year

string

MM/YYYY label

object

sentiment, alignment, consistency, factualAlignment

string

Completion timestamp (ISO 8601) or null

object

months (requested window) and dataPoints (number of snapshots returned).

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

Getting Started

Setup

Cockpit

Monitor

Analyze

Act

Optimize

Agencies

Webhooks

Guides

Brand Perception

Path Parameters

Query Parameters

Response

Example Request

Example Response

​Path Parameters

​Query Parameters

​Response

​Example Request

​Example Response

Path Parameters

Query Parameters

Response

Example Request

Example Response