---
title: "Active sports games with urgency scores and cross-provider prices"
method: GET
path: "/sports/live-events"
tags: ["Sports"]
---

# Active sports games with urgency scores and cross-provider prices

`GET /sports/live-events`

## Request

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

Returns active game IDs plus, when the provider indexing gate has `predictfun` enabled, open Predict.fun fixtures inside their scheduled start/end window. The gate is re-checked on every request (including cache hits); a gate lookup failure excludes Predict.fun (fail closed) without dropping Polymarket/Kalshi rows. Hydrates current state, drops ended games idle for more than a few minutes, and computes an `urgencyScore`/`stale` flag per game. Enriches each event with cached primary-market data, falling back to a live provider lookup when the cache is cold. Resolves each event's matching Polymarket/Kalshi slug and attaches the corresponding cross-venue match record into `matchingMarkets`. If no matched entry anywhere carries a Kalshi side, synthesizes one from a team-name-matching fallback lookup. Results are sorted by most-recent update, then by `urgencyScore` descending. Served from a shared server cache rebuilt about every 5 seconds while the endpoint is in use and never more than 60 seconds old; the `Age` header gives the seconds since the body was built.

## Query parameters

- `include_markets` boolean

## Response `200`

Active games ordered by recency then urgency, plus their matched cross-provider markets.

- SportsLiveEventsResponse
  - `events` SportsLiveEvent[], required
    - `timing` SportsTiming, required: Conservative timing evidence. Polymarket elapsed is not normalized to remaining time. Predict.fun schedule windows do not establish live score freshness. Consumers must age stateAgeSeconds from evaluatedAt because responses can be cached.
      - `source` 'polymarket' | 'predictfun', required
      - `status` 'scheduled' | 'live' | 'break' | 'overtime' | 'shootout' | 'suspended' | 'delayed' | 'postponed' | 'cancelled' | 'final' | 'unknown', required
      - `clock` string, nullable, required
      - `clockDirection` 'unknown', required
      - `clockRunning` boolean, nullable, required: Currently null; running state is not established.
      - `periodRemainingSeconds` number, nullable, required: Currently null; do not derive this from elapsed without verified clock semantics.
      - `gameRemainingSeconds` number, nullable, required: Currently null; overtime and eventual completion cannot be inferred from regulation time.
      - `overtime` boolean, nullable, required: True for explicit OT or extra-time evidence, false for regulation final FT, otherwise null. Completion after overtime is not active overtime.
      - `stateAgeSeconds` number, nullable, required
      - `evaluatedAt` string, date-time, required
      - `staleAfterSeconds` 120, required
      - `stale` boolean, required
      - `usableForLateGame` false, required: No authoritative countdown is currently available from these sources.
      - `unavailableReason` 'unknown_clock_semantics' | 'missing_clock' | 'game_not_in_play' | 'stale_state' | 'invalid_timestamp' | 'no_live_score_feed', required
    - `gameId` string, required
    - `sport` string, required: Lowercased league abbreviation.
    - `sportFamily` string, required: Canonical category id from the sports catalog.
    - `homeTeam` string, required
    - `awayTeam` string, required
    - `homeScore` integer, required: Series score if the game has one, else the game score.
    - `awayScore` integer, required
    - `status` string, required
    - `period` string, nullable, required
    - `elapsed` string, nullable, required: Opaque provider clock string; direction, period resets, and overtime semantics are not verified.
    - `live` boolean, required
    - `ended` boolean, required
    - `slug` string, nullable, required
    - `matchingSlug` string, nullable, required: Slug used as the key into matchingMarkets.
    - `ts` string, date-time, required: Game-state observation timestamp; source observation time when available, otherwise time received by Kairos.
    - `urgencyScore` integer, required: Candidate-ranking heuristic for fresh games explicitly in play. Zero for stale, stopped, ended, unknown-status, and schedule-only games. Not a remaining-time signal.
    - `stale` boolean, required: True for state older than 120 seconds, invalid or future timestamps, timestamps without a timezone, or absence of a live score feed. Evaluated at timing.evaluatedAt.
    - `primaryMarket` SportsNormalizedMarket, required: Upstream market normalized into a common shape used across the live-events, event-markets, and upcoming-events endpoints.
      - `id` string, required
      - `question` string, required
      - `slug` string, required
      - `conditionId` string, required
      - `tokenId` string, required: First clobTokenId for the market.
      - `outcomePrices` number[], required
      - `outcomes` string[], required
      - `volumeNum` number, double, required
      - `liquidityNum` number, double, required
      - `acceptingOrders` boolean, required
      - `sportsMarketType` string, nullable, required
      - `groupItemTitle` string, nullable, required
      - `gameStartTime` string, date-time, nullable: Scheduled fixture kickoff used for cross-provider live-game matching.
      - `bestBid` number, double, nullable, required
      - `bestAsk` number, double, nullable, required
      - `spread` number, double, nullable, required
      - `provider` string, required
      - `image` string, nullable, required
      - `icon` string, nullable, required
      - `outcomeMarketIds` string[]: Only present on 3-way (soccer moneyline) composite markets. Length 3, [home, draw, away].
      - `outcomeTokenIds` string[]: Per-outcome token IDs in the same order as outcomes, when available.
      - `outcomeConditionIds` string[]: Only present on 3-way composite markets.
    - `marketsCount` integer, required
    - `markets` SportsNormalizedMarket[]: Present only when include_markets=true.
      - `id` string, required
      - `question` string, required
      - `slug` string, required
      - `conditionId` string, required
      - `tokenId` string, required: First clobTokenId for the market.
      - `outcomePrices` number[], required
      - `outcomes` string[], required
      - `volumeNum` number, double, required
      - `liquidityNum` number, double, required
      - `acceptingOrders` boolean, required
      - `sportsMarketType` string, nullable, required
      - `groupItemTitle` string, nullable, required
      - `gameStartTime` string, date-time, nullable: Scheduled fixture kickoff used for cross-provider live-game matching.
      - `bestBid` number, double, nullable, required
      - `bestAsk` number, double, nullable, required
      - `spread` number, double, nullable, required
      - `provider` string, required
      - `image` string, nullable, required
      - `icon` string, nullable, required
      - `outcomeMarketIds` string[]: Only present on 3-way (soccer moneyline) composite markets. Length 3, [home, draw, away].
      - `outcomeTokenIds` string[]: Per-outcome token IDs in the same order as outcomes, when available.
      - `outcomeConditionIds` string[]: Only present on 3-way composite markets.
  - `matchingMarkets` object, required: Map keyed by matched slug, one entry per event that resolved a matchingSlug.

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

---

[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)