Skip to main content
GET
/
v1
/
brands
/
{brandId}
/
runs
List runs
curl --request GET \
  --url https://api.example.com/v1/brands/{brandId}/runs
{
  "data": [
    {
      "id": "<string>",
      "startedAt": {},
      "metrics": {}
    }
  ],
  "paging": {}
}

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.

An analysis run is a complete processing pass for a brand: collecting LLM responses, scoring presence and sentiment, and computing summary metrics. Use this endpoint to build a run history picker, or to check the latest aggregate stats before diving into per-prompt results.

​
Path parameters

​
brandId
string
required
The brand UUID. Obtain it from List brands.

​
Query parameters

​
limit
integer
default:"10"
Items per page. Maximum 500.
​
page
integer
default:"1"
Page number (1-based).

​
Request

curl -s \
  -H "x-spotlight-api-key: YOUR_API_KEY" \
  "https://app.get-spotlight.com/api/v1/brands/BRAND_ID/runs?limit=10&page=1"

​
Response

​
data
Run[]
Array of run objects.
​
paging
Paging
See Pagination.
{
  "data": [
    {
      "id": "run-uuid-123",
      "startedAt": "2025-02-01T10:00:00Z",
      "metrics": {
        "present": 120,
        "positive": 80,
        "negative": 20,
        "neutral": 20,
        "responsesWithBrands": 100,
        "totalResponses": 150,
        "completedResponses": 150,
        "averageRank": 1.8,
        "topics": null,
        "calculatedAt": "2025-02-01T10:30:00Z"
      }
    }
  ],
  "paging": { "page": 1, "limit": 10, "total": 3, "nextPage": null }
}
If a completed run has not had its metrics calculated yet, the API triggers an automatic refresh and returns updated metrics. You always receive accurate numbers.