Get brand perception

Return perception prompts and scored responses for a brand.

GET /v1/brands/{brandId}/perception

Get brand perception

cURL

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

200

{
  "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 — latest run

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.

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