---
title: "List events"
method: GET
path: "/v1/events"
tags: ["events"]
---

# List events

`GET /v1/events`

## Request

- Base URL: `https://lumify.ai`
- URL: `https://lumify.ai/v1/events`
- Auth: HTTP bearer

## Query parameters

- `sport` string, nullable: Sport slug: nfl, nba, mlb, nhl, tennis, soccer…
- `league` string, nullable: League slug: nfl, nba, atp, mls…
- `status` string, nullable: Event status: scheduled|inprogress|final|…
- `date` string, nullable: UTC date YYYY-MM-DD (single day)
- `from` string, nullable: UTC start date YYYY-MM-DD
- `to` string, nullable: UTC end date YYYY-MM-DD (inclusive)
- `season_id` integer, nullable: Filter by season ID
- `team_id` integer, nullable: Filter to events where this team participates. Resolve ids via GET /v1/teams?q=…
- `after_id` integer, nullable: Cursor: return events with id > after_id
- `limit` integer
- `include_scores` boolean: Inline participants + scores in each event. Intended for small result sets (≤ 200 events). Shares the 20/min score-poll budget with GET /events/{id}/score; prefer GET /events/{id}/stream for live boards.
- `has_recommend` boolean, nullable: When true, return only events with at least one recommended bet (has_recommend=1 in intelligence). Requires intelligence pipeline to have run.
- `sort` string: Sort order: 'time' (chronological, default) or 'status' (Live → Delayed/Upcoming → Final → Cancelled/Postponed). Cursor pagination (after_id) is not supported with sort=status.

## Response `200`

Paginated event list, newest first within the requested window

- EventListResponse
  - `events` EventSummary[]
    - `id` integer, required
    - `name` string, nullable
    - `sport` string, nullable
    - `league` string, nullable
    - `season_id` integer, nullable
    - `starts_at` string, nullable: ISO-8601 UTC start time.
    - `inprogress_since` string, nullable: ISO-8601 UTC timestamp of the first ingest that marked this event inprogress (first live tick). Null until then; stays set after final. Walkovers and events that never went live are usually null. Not the same as starts_at, which can be a session floor (especially tennis).
    - `status` string, nullable
    - `period` string, nullable
    - `clock` string, nullable
    - `venue` object, nullable
  - `total` integer
  - `next_after_id` integer, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api.md) · [All operations](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api/revisions/f91ea41a2606?raw)