---
title: "Upcoming (not-yet-live) sports events within a time window"
method: GET
path: "/sports/upcoming-events"
tags: ["Sports"]
---

# Upcoming (not-yet-live) sports events within a time window

`GET /sports/upcoming-events`

## Request

- Base URL: `https://data.kairos.trade`
- URL: `https://data.kairos.trade/sports/upcoming-events`
- Auth: none required

Returns fixtures in the requested league set whose scheduled start falls within `windowHours`, together with primary markets, combo eligibility where available, and cross-venue matches for Polymarket, Kalshi, Predict.fun, and Hyperliquid. Provider-only fixtures may be returned as standalone events. Served from a shared server cache rebuilt about every minute; a copy is never more than two hours old for the default 720h/200 and 168h/12 windows, which are kept warm, or ten minutes old for any other window; the `Age` header gives the seconds since the body was built. `startFrom`/`startTo` return one slice of the window by start time, for loading a schedule a few days at a time. Returns 502 when no provider can supply data and 504 when a cold build runs out of time.

## Query parameters

- `windowHours` integer
- `category` string
- `league` string
- `series` string
- `limitPerSeries` integer
- `startFrom` string, date-time
- `startTo` string, date-time

## Response `200`

Upcoming events within the window, plus matched cross-provider markets. Returns `{"events": [], "startingEvents": [], "matchingMarkets": {}}` on a genuine no-data result.

- SportsUpcomingEventsResponse
  - `events` SportsUpcomingEvent[], required
    - `eventId` string, required
    - `title` string, required
    - `startTime` string, date-time, required: Normalized ISO8601 gameStartTime (endDate fallback for events missing it).
    - `sport` string, required: Broad sport family used for display and grouping.
    - `sportFamily` string, required: Canonical category id from the sports catalog; equal to sport on this route.
    - `league` string, required: Sports-catalog league slug.
    - `teamA` string, nullable, required
    - `teamB` string, nullable, required
    - `image` string, nullable, required
    - `primaryMarket` SportsUpcomingMarket, required
      - `id` string, required
      - `provider` 'polymarket' | 'kalshi' | 'predictfun', required
      - `question` string, required
      - `slug` string, required
      - `conditionId` string, required
      - `tokenId` string, required
      - `outcomePrices` number[], required
      - `outcomes` string[], required
      - `volumeNum` number, double, required
      - `liquidityNum` number, double, required
      - `acceptingOrders` boolean, required
      - `sportsMarketType` string, nullable, required
      - `gameId` unknown, required
      - `outcomeMarketIds` string[]: Only present on 3-way (soccer) composite markets. [home, draw, away].
      - `outcomeTokenIds` string[]: Only present on 3-way composite markets.
      - `outcomeConditionIds` string[]: Only present on 3-way composite markets.
    - `marketsCount` integer, required
    - `eventSlug` string, nullable, required: Venue fixture slug accepted by the cross-venue game-markets catalog.
    - `matchingSlug` string, nullable: Alternate market slug under which cross-venue matches may be published.
    - `startingEligible` boolean: True when a known kickoff lets the fixture enter the starting grace window.
    - `awaitingLive` boolean: True only in startingEvents; it does not confirm that the game is live.
    - `drawPrice` number, double, nullable, required: Present for soccer 3-way events.
    - `teamBPrice` number, double, nullable, required: Present for soccer 3-way events.
  - `startingEvents` SportsUpcomingEvent[], required: Fixtures whose scheduled start was within the last ten minutes but which have not yet appeared in the live feed. These are schedule-derived, not confirmed live.
    - `eventId` string, required
    - `title` string, required
    - `startTime` string, date-time, required: Normalized ISO8601 gameStartTime (endDate fallback for events missing it).
    - `sport` string, required: Broad sport family used for display and grouping.
    - `sportFamily` string, required: Canonical category id from the sports catalog; equal to sport on this route.
    - `league` string, required: Sports-catalog league slug.
    - `teamA` string, nullable, required
    - `teamB` string, nullable, required
    - `image` string, nullable, required
    - `primaryMarket` SportsUpcomingMarket, required
      - `id` string, required
      - `provider` 'polymarket' | 'kalshi' | 'predictfun', required
      - `question` string, required
      - `slug` string, required
      - `conditionId` string, required
      - `tokenId` string, required
      - `outcomePrices` number[], required
      - `outcomes` string[], required
      - `volumeNum` number, double, required
      - `liquidityNum` number, double, required
      - `acceptingOrders` boolean, required
      - `sportsMarketType` string, nullable, required
      - `gameId` unknown, required
      - `outcomeMarketIds` string[]: Only present on 3-way (soccer) composite markets. [home, draw, away].
      - `outcomeTokenIds` string[]: Only present on 3-way composite markets.
      - `outcomeConditionIds` string[]: Only present on 3-way composite markets.
    - `marketsCount` integer, required
    - `eventSlug` string, nullable, required: Venue fixture slug accepted by the cross-venue game-markets catalog.
    - `matchingSlug` string, nullable: Alternate market slug under which cross-venue matches may be published.
    - `startingEligible` boolean: True when a known kickoff lets the fixture enter the starting grace window.
    - `awaitingLive` boolean: True only in startingEvents; it does not confirm that the game is live.
    - `drawPrice` number, double, nullable, required: Present for soccer 3-way events.
    - `teamBPrice` number, double, nullable, required: Present for soccer 3-way events.
  - `matchingMarkets` object, required

## Other responses

- `422`: Request failed FastAPI parameter validation.
- `429`: Rate limit exceeded for this route's sliding window, keyed on the session `sub` when authenticated and on the trusted client IP otherwise. Honor `Retry-After`. A per-API-key data ceiling (set per credential) rejects with `{"detail": "API key data rate limit exceeded"}` instead of the `error` envelope below.
- `502`: All upstream event-source fetches failed while building a cold cache entry.

---

[API](https://skmtc.dev/kairos/apis/kairos-data-api.md) - [All operations](https://skmtc.dev/kairos/apis/kairos-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kairos/apis/kairos-data-api/revisions/cf6b76079e38?raw)