> ## Documentation Index > Fetch the complete documentation index at: https://docs.kairos.trade/llms.txt > Use this file to discover all available pages before exploring further. # Upcoming (not-yet-live) sports events within a time window > 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. ## OpenAPI ````yaml /openapi/data-api.yaml get /sports/upcoming-events openapi: 3.1.0 info: title: Kairos Data API version: 1.0.0 summary: >- The full Kairos data plane — markets, candles, trades, search, discover, sports, trader analytics, and PnL. description: | The Kairos Data API at `data.kairos.trade` is the platform's primary data plane: market metadata and prices, OHLCV candles, live venue trade proxies, normalized trade history, full-text search, discovery feeds, the sports catalog, public trader analytics, and account PnL. ## Authentication Most endpoints accept a Kairos **API key** (`X-Client-Id` + `X-Api-Key` + `X-Api-Secret`, all three) or a first-party session JWT. Endpoints tagged `public` (trader analytics, provider configs, several sports feeds) need no credentials at all. Some endpoints additionally require an API-key **scope** (`trade:read`, `position:read`) — stated per operation. For high-volume market-data consumption (candles/trades/metadata at scale), prefer the dedicated **Market Data API** at `md.kairos.trade` — it has higher budgets, ETag caching, and a binary candle format. ## Rate limits Rate limits use a sliding window keyed on the authenticated user (JWT `sub`) or, for anonymous callers, the trusted client IP. Routes belong to a named **bucket** (`x-kairos-bucket`) whose per-minute budget is shared by every route in it; routes with no bucket run under the service default of 100/minute. `x-kairos-rate-limit` states the bucket's compile-time default — operators can raise or lower a bucket at runtime, so treat the documented number as the baseline, not a contract. 429 responses carry `Retry-After` and `X-RateLimit-*`. ## Conventions - Prices are on the **0–100 cents scale** unless a field says otherwise (trader-analytics position/trade prices use the 0–1 scale; each field's description states its scale). - Errors: `{"detail": ""}` for handler errors; FastAPI's standard validation envelope for 422s. Errors surfaced from a venue adapter instead use `{"error", "provider", "operation", "message"}` — see `DataProviderError`. Unhandled failures always return the generic 500 body; internal details are logged, never returned. - Every request body is capped at 8 MiB service-wide (413). contact: name: Kairos url: https://app.kairos.trade/docs/api-reference termsOfService: https://kairos.trade/terms servers: - url: https://data.kairos.trade description: Production - url: https://staging-data.kairos.trade description: Staging security: - apiKeyClientId: [] apiKeyKey: [] apiKeySecret: [] paths: /sports/upcoming-events: get: tags: - Sports summary: Upcoming (not-yet-live) sports events within a time window description: >- 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. operationId: getSportsUpcomingEvents parameters: - name: windowHours in: query required: false description: Look-ahead window, in hours, for upcoming game start times. schema: type: integer minimum: 1 maximum: 720 default: 24 example: 24 - name: category in: query required: false description: >- Sports-catalog category id (e.g. "basketball"). Expands to every league slug in that category and takes priority over league/series. schema: type: string example: basketball - name: league in: query required: false description: >- Single league slug filter (e.g. "nba"). Used only if category is not supplied or does not resolve. schema: type: string example: nba - name: series in: query required: false description: >- Comma-separated league slugs. Used only if neither category nor league resolves. schema: type: string example: nba,nhl - name: limitPerSeries in: query required: false description: Maximum number of events fetched per resolved series. schema: type: integer minimum: 1 maximum: 200 default: 12 example: 12 - name: startFrom in: query required: false description: >- Only events starting at or after this instant (ISO 8601 with a UTC offset). `startingEvents` are included only in the slice that covers the current time, and `matchingMarkets` only holds entries for the events returned. schema: type: string format: date-time example: '2026-09-25T04:00:00Z' - name: startTo in: query required: false description: >- Only events starting before this instant (ISO 8601 with a UTC offset). Must be after `startFrom`. schema: type: string format: date-time example: '2026-09-28T04:00:00Z' responses: '200': description: >- Upcoming events within the window, plus matched cross-provider markets. Returns `{"events": [], "startingEvents": [], "matchingMarkets": {}}` on a genuine no-data result. headers: Cache-Control: schema: type: string example: public, max-age=30, s-maxage=60 content: application/json: schema: $ref: '#/components/schemas/SportsUpcomingEventsResponse' '422': $ref: '#/components/responses/DataValidationError' '429': $ref: '#/components/responses/DataRateLimited' '502': description: >- All upstream event-source fetches failed while building a cold cache entry. content: application/json: schema: type: object properties: detail: type: string example: All upstream fetches failed security: [] components: schemas: SportsUpcomingEventsResponse: type: object required: - events - startingEvents - matchingMarkets properties: events: type: array items: $ref: '#/components/schemas/SportsUpcomingEvent' startingEvents: type: array description: >- 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. items: $ref: '#/components/schemas/SportsUpcomingEvent' matchingMarkets: type: object additionalProperties: $ref: '#/components/schemas/SportsUpcomingMatchingEntry' SportsUpcomingEvent: type: object required: - eventId - title - startTime - sport - sportFamily - league - teamA - teamB - image - primaryMarket - marketsCount - eventSlug - drawPrice - teamBPrice properties: eventId: type: string example: '10078222' title: type: string example: Lakers at Celtics startTime: type: string format: date-time description: >- Normalized ISO8601 gameStartTime (endDate fallback for events missing it). sport: type: string description: Broad sport family used for display and grouping. example: soccer sportFamily: type: string description: >- Canonical category id from the sports catalog; equal to sport on this route. example: soccer league: type: string description: Sports-catalog league slug. example: uel teamA: type: - string - 'null' example: Los Angeles Lakers teamB: type: - string - 'null' example: Boston Celtics image: type: - string - 'null' primaryMarket: oneOf: - $ref: '#/components/schemas/SportsUpcomingMarket' - type: 'null' marketsCount: type: integer example: 4 eventSlug: type: - string - 'null' description: Venue fixture slug accepted by the cross-venue game-markets catalog. example: nba-lal-bos-2026-01-15 matchingSlug: type: - string - 'null' description: >- Alternate market slug under which cross-venue matches may be published. startingEligible: type: boolean description: >- True when a known kickoff lets the fixture enter the starting grace window. awaitingLive: type: boolean description: >- True only in startingEvents; it does not confirm that the game is live. drawPrice: type: - number - 'null' format: double description: Present for soccer 3-way events. teamBPrice: type: - number - 'null' format: double description: Present for soccer 3-way events. SportsUpcomingMatchingEntry: type: object required: - providers properties: providers: type: array items: $ref: '#/components/schemas/SportsUpcomingMatchingProvider' SportsUpcomingMarket: type: object required: - id - provider - question - slug - conditionId - tokenId - outcomePrices - outcomes - volumeNum - liquidityNum - acceptingOrders - sportsMarketType - gameId properties: id: type: string provider: type: string enum: - polymarket - kalshi - predictfun question: type: string slug: type: string conditionId: type: string tokenId: type: string outcomePrices: type: array items: type: number format: double outcomes: type: array items: type: string volumeNum: type: number format: double liquidityNum: type: number format: double acceptingOrders: type: boolean sportsMarketType: type: - string - 'null' gameId: description: Raw upstream game id, type varies by provider. nullable: true outcomeMarketIds: type: array description: >- Only present on 3-way (soccer) composite markets. [home, draw, away]. items: type: - string - 'null' outcomeTokenIds: type: array description: Only present on 3-way composite markets. items: type: - string - 'null' outcomeConditionIds: type: array description: Only present on 3-way composite markets. items: type: - string - 'null' SportsUpcomingMatchingProvider: type: object required: - provider - price - marketId - eventTicker - volume properties: provider: type: string enum: - polymarket - kalshi - predictfun - hyperliquid price: type: - number - 'null' format: double marketId: type: string eventTicker: type: - string - 'null' volume: type: - number - 'null' format: double source: type: string description: >- Present as `market_matcher` when cross-venue identity matching supplied the entry. responses: DataValidationError: description: Request failed FastAPI parameter validation. content: application/json: schema: type: object required: - detail properties: detail: type: array description: >- One entry per failed field, with location, message, and error type. items: type: object additionalProperties: true DataRateLimited: description: > 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. headers: Retry-After: schema: type: integer X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer content: application/json: schema: type: object properties: error: type: string example: 'Rate limit exceeded: 100 per 1 minute' securitySchemes: apiKeyClientId: type: apiKey in: header name: X-Client-Id description: >- Credential client id (`kairos_ck_...`). Must be sent together with X-Api-Key and X-Api-Secret. apiKeyKey: type: apiKey in: header name: X-Api-Key description: 64-char hex API key. apiKeySecret: type: apiKey in: header name: X-Api-Secret description: 64-char hex API secret. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.