> ## 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.

# Get brand perception

> Return perception prompts and scored responses for a brand.

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

<ParamField path="brandId" type="string" required>
  Brand UUID. Obtain from [List brands](/api-reference/brands/list).
</ParamField>

### Query parameters

<ParamField query="runId" type="string">
  Target a specific run. If omitted, the most recent run is used.
</ParamField>

### Request

<CodeGroup>
  ```bash cURL — latest run theme={null}
  curl -s \
    -H "x-spotlight-api-key: YOUR_API_KEY" \
    "https://app.get-spotlight.com/api/v1/brands/BRAND_ID/perception"
  ```

  ```bash cURL — specific run theme={null}
  curl -s \
    -H "x-spotlight-api-key: YOUR_API_KEY" \
    "https://app.get-spotlight.com/api/v1/brands/BRAND_ID/perception?runId=RUN_ID"
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

### Response

<ResponseField name="run" type="object | null">
  The run these responses are tied to, or `null` if no run was found.

  <Expandable title="Run" />
</ResponseField>

<ResponseField name="data" type="PerceptionPrompt[]">
  Array of perception prompts with responses.

  <Expandable title="PerceptionPrompt object">
    <ResponseField name="responses" type="PerceptionResponse[]">
      One response per LLM (latest per LLM if multiple runs).

      <Expandable title="PerceptionResponse object" />
    </ResponseField>
  </Expandable>
</ResponseField>

```json theme={null}
{
  "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"
        }
      ]
    }
  ]
}
```