Get brand perception

GET

brands

{brandId}

perception

curl --request GET \
  --url https://api.example.com/v1/brands/{brandId}/perception

import requests

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

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.example.com/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/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",
]);

$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/v1/brands/{brandId}/perception"

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

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.example.com/v1/brands/{brandId}/perception")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)

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

{
  "run": {},
  "data": [
    {
      "responses": [
        {}
      ]
    }
  ]
}

Perception prompts are questions like “How trustworthy does this brand appear?” that are sent to multiple LLMs. Each response includes a numeric score and reasoning. Use this endpoint to:

Build NPS-style perception dashboards per property
Compare how different LLMs score and describe the same trait
Feed perception metrics into BI tools or internal reports

Path parameters

brandId

string

required

Brand UUID. Obtain from List brands.

Query parameters

runId

string

Target a specific run. If omitted, the most recent run is used.

Request

curl -s \
  -H "x-spotlight-api-key: YOUR_API_KEY" \
  "https://app.get-spotlight.com/api/v1/brands/BRAND_ID/perception"

curl -s \
  -H "x-spotlight-api-key: YOUR_API_KEY" \
  "https://app.get-spotlight.com/api/v1/brands/BRAND_ID/perception?runId=RUN_ID"

import requests

r = requests.get(
    "https://app.get-spotlight.com/api/v1/brands/BRAND_ID/perception",
    headers={"x-spotlight-api-key": "YOUR_API_KEY"},
    params={"runId": "RUN_ID"},  # optional
)
print(r.json())

Response

run

object | null

The run these responses are tied to, or null if no run was found.

Show Run

data

PerceptionPrompt[]

Array of perception prompts with responses.

Show PerceptionPrompt object

responses

PerceptionResponse[]

One response per LLM (latest per LLM if multiple runs).

Show PerceptionResponse object

{
  "brandId": "brand-uuid-123",
  "run": { "id": "run-uuid-123", "startedAt": "2025-02-01T10:00:00Z" },
  "data": [
    {
      "id": "perception-prompt-uuid-1",
      "propertyId": "Trust",
      "promptText": "On a scale from 0 to 10, how trustworthy does this brand appear?",
      "scoringLogic": "0-6: detractor, 7-8: passive, 9-10: promoter",
      "createdAt": "2025-01-15T09:00:00Z",
      "responses": [
        {
          "id": "response-uuid-1",
          "llm": "chatgpt",
          "response": "Customers generally see the brand as trustworthy, but some mention confusing pricing.",
          "score": 8.5,
          "scoreReason": "Mostly positive trust signals with a few concerns.",
          "isUserChanged": false,
          "createdAt": "2025-02-01T10:05:00Z"
        }
      ]
    }
  ]
}

Get run perceptionReturn perception data for a specific run.

Get brand perception

curl --request GET \
  --url https://api.example.com/v1/brands/{brandId}/perception

import requests

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

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://api.example.com/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/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",
]);

$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/v1/brands/{brandId}/perception"

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

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.example.com/v1/brands/{brandId}/perception")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)

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

{
  "run": {},
  "data": [
    {
      "responses": [
        {}
      ]
    }
  ]
}

Get Started

API Reference

Path parameters

Query parameters

Request

Response

​Path parameters

​Query parameters

​Request

​Response

Path parameters

Query parameters

Request

Response