Pagination

How paging works across list endpoints.

Query parameters

All list endpoints accept these two query parameters:

limit · integer · default: "varies"

Number of items to return per page. Must be a positive integer. Capped at 500.

page · integer · default: "1"

1-based page index.

Paging response object

Paginated endpoints return a paging object alongside the data array:

{
  "data": [...],
  "paging": {
    "page": 1,
    "limit": 50,
    "total": 214,
    "nextPage": 2
  }
}

Field	Type	Description
page	integer	Current page number.
limit	integer	Effective limit used for this response.
total	integer | null	Total matching rows. May be null on some endpoints.
nextPage	integer | null	Next page number, or null if this is the last page.

Walking all pages

import requests

BASE_URL = "https://app.get-spotlight.com/api"
HEADERS  = {"x-spotlight-api-key": "YOUR_API_KEY"}

page, results = 1, []
while True:
    r = requests.get(
        f"{BASE_URL}/v1/runs/RUN_ID",
        headers=HEADERS,
        params={"limit": 500, "page": page},
    ).json()
    results.extend(r["data"])
    if r["paging"]["nextPage"] is None:
        break
    page += 1

Internal limits

The database enforces a hard 2000-row cap per query. For heavy endpoints like /sources, the API fetches data in internal batches and merges results before responding — you do not need to handle this yourself.