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

# List runs

> List analysis runs for a brand with aggregate metrics.

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

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

### Query parameters

<ParamField query="limit" default="10" type="integer">
  Items per page. Maximum 500.
</ParamField>

<ParamField query="page" default="1" type="integer">
  Page number (1-based).
</ParamField>

### Request

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```python Python theme={null}
  import requests

  r = requests.get(
      "https://app.get-spotlight.com/api/v1/brands/BRAND_ID/runs",
      headers={"x-spotlight-api-key": "YOUR_API_KEY"},
      params={"limit": 10, "page": 1},
  )
  print(r.json())
  ```

  ```javascript JavaScript theme={null}
  const r = await fetch(
    "https://app.get-spotlight.com/api/v1/brands/BRAND_ID/runs?limit=10&page=1",
    { headers: { "x-spotlight-api-key": "YOUR_API_KEY" } }
  );
  const json = await r.json();
  ```
</CodeGroup>

### Response

<ResponseField name="data" type="Run[]">
  Array of run objects.

  <Expandable title="Run object">
    <ResponseField name="id" type="string">
      Run UUID — use as `{runId}` in other endpoints.
    </ResponseField>

    <ResponseField name="startedAt" type="string (ISO 8601)">
      When the run began.
    </ResponseField>

    <ResponseField name="metrics" type="object">
      Aggregate statistics for the run.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="paging" type="Paging">
  See [Pagination](/pagination).
</ResponseField>

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

<Info>
  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.
</Info>