Skip to main content
GET
/
v1
/
brands
/
{brandId}
/
perception
Get brand perception
curl --request GET \
  --url https://api.example.com/v1/brands/{brandId}/perception
{
  "run": {},
  "data": [
    {
      "responses": [
        {}
      ]
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.get-spotlight.com/llms.txt

Use this file to discover all available pages before exploring further.

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"

​
Response

​
run
object | null
The run these responses are tied to, or null if no run was found.
​
data
PerceptionPrompt[]
Array of perception prompts with responses.
{
  "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"
        }
      ]
    }
  ]
}