> ## 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. # Score, timeline, and possession metrics for one fixture > Full detail for a single fixture: scoreline, event timeline, and possession-derived metrics. Independent parts are read concurrently and degrade individually — a part that fails is returned in its empty shape rather than failing the response, and the degraded payload is cached for a shorter time than a clean one. Possession metrics are soccer-only; `usfootball` fixtures carry their situational state in `football` instead. ## OpenAPI ````yaml /openapi/data-api.yaml get /txodds/fixtures/{fixture_id} 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: /txodds/fixtures/{fixture_id}: get: tags: - Sports summary: Score, timeline, and possession metrics for one fixture description: > Full detail for a single fixture: scoreline, event timeline, and possession-derived metrics. Independent parts are read concurrently and degrade individually — a part that fails is returned in its empty shape rather than failing the response, and the degraded payload is cached for a shorter time than a clean one. Possession metrics are soccer-only; `usfootball` fixtures carry their situational state in `football` instead. operationId: getTxoddsFixture parameters: - name: fixture_id in: path required: true schema: type: integer minimum: 1 exclusiveMaximum: 9223372036854776000 example: 4821993 responses: '200': description: Fixture detail, possibly degraded. content: application/json: schema: $ref: '#/components/schemas/TxoddsFixtureDetail' '401': $ref: '#/components/responses/DataUnauthorized' '403': $ref: '#/components/responses/DataForbidden' '404': description: >- No such fixture. Misses are cached, so a repeated probe for an unknown id does not reach the store. content: application/json: schema: $ref: '#/components/schemas/DataError' example: detail: fixture 4821993 not found '422': $ref: '#/components/responses/DataValidationError' '429': $ref: '#/components/responses/DataRateLimited' components: schemas: TxoddsFixtureDetail: type: object description: Everything the match detail view renders, from the score event store. required: - fixtureId - competitionId - competition - home - away - kickoff - status - score - timeline - metrics properties: fixtureId: type: integer competitionId: type: integer competition: type: string home: $ref: '#/components/schemas/TxoddsTeamRef' away: $ref: '#/components/schemas/TxoddsTeamRef' kickoff: type: integer status: type: string sport: type: string default: soccer football: oneOf: - $ref: '#/components/schemas/TxoddsFootballState' - type: 'null' score: $ref: '#/components/schemas/TxoddsScoreStats' timeline: type: array items: $ref: '#/components/schemas/TxoddsTimelineEvent' metrics: $ref: '#/components/schemas/TxoddsMetrics' DataError: type: object description: Handler error envelope (FastAPI HTTPException). required: - detail properties: detail: type: string description: Human-readable error message. example: Invalid provider TxoddsTeamRef: type: object required: - code - name properties: code: type: string name: type: string TxoddsFootballState: type: object description: >- US-football situational state. Present only when `sport` is `usfootball`. required: - homePoints - awayPoints - touchdowns - fieldGoals - periodScores properties: homePoints: type: integer awayPoints: type: integer touchdowns: type: array items: type: integer fieldGoals: type: array items: type: integer onePointConversions: type: array items: type: integer twoPointConversions: type: array items: type: integer safeties: type: array items: type: integer periodScores: type: array items: $ref: '#/components/schemas/TxoddsFootballPeriodScore' down: oneOf: - $ref: '#/components/schemas/TxoddsFootballDown' - type: 'null' clockSeconds: type: - integer - 'null' clockRunning: type: boolean default: false redZone: type: boolean default: false phase: type: string default: '' TxoddsScoreStats: type: object description: >- Latest score state. Soccer-shaped; gridiron fixtures carry their counters in `football`. required: - gameState - homeGoals - awayGoals - homeYellow - awayYellow - homeRed - awayRed - homeCorners - awayCorners - possessionHome - possessionAway - shotsHome - shotsAway - shotsOnTargetHome - shotsOnTargetAway - updateCount properties: gameState: type: string homeGoals: type: integer awayGoals: type: integer homeYellow: type: integer awayYellow: type: integer homeRed: type: integer awayRed: type: integer homeCorners: type: integer awayCorners: type: integer possessionHome: type: - number - 'null' possessionAway: type: - number - 'null' shotsHome: type: - integer - 'null' shotsAway: type: - integer - 'null' shotsOnTargetHome: type: - integer - 'null' shotsOnTargetAway: type: - integer - 'null' updateCount: type: integer currentHolder: type: - string - 'null' possessionThreat: type: - string - 'null' TxoddsTimelineEvent: type: object required: - ts - seq - minute - action - gameState - homeGoals - awayGoals - side - data properties: ts: type: integer description: Event time, epoch milliseconds. seq: type: integer minute: type: - integer - 'null' action: type: string gameState: type: string homeGoals: type: integer awayGoals: type: integer side: type: - string - 'null' data: type: string detail: type: - string - 'null' TxoddsMetrics: type: object description: >- Possession-derived metrics. Empty shapes for gridiron fixtures, which emit no possession events, and for any part that failed while the rest of the detail loaded. required: - avgPossessionHome - avgPossessionAway - momentum - conversion - turnover properties: avgPossessionHome: type: - number - 'null' avgPossessionAway: type: - number - 'null' momentum: type: array items: $ref: '#/components/schemas/TxoddsMomentumPoint' conversion: $ref: '#/components/schemas/TxoddsConversion' turnover: $ref: '#/components/schemas/TxoddsTurnover' TxoddsFootballPeriodScore: type: object required: - period - home - away properties: period: type: string home: type: integer away: type: integer TxoddsFootballDown: type: object required: - number - yardsToGo - possession properties: number: type: integer yardsToGo: type: integer yardsToEndzone: type: - integer - 'null' possession: type: string TxoddsMomentumPoint: type: object required: - minute - home - away properties: minute: type: integer home: type: integer away: type: integer TxoddsConversion: type: object required: - homeShots - awayShots - homeConversion - awayConversion properties: homeShots: type: - integer - 'null' awayShots: type: - integer - 'null' homeConversion: type: - number - 'null' awayConversion: type: - number - 'null' TxoddsTurnover: type: object required: - switches - perMinute properties: switches: type: integer perMinute: type: - number - 'null' responses: DataUnauthorized: description: > No valid credential presented — missing/invalid API-key headers, or an invalid/expired session token. content: application/json: schema: $ref: '#/components/schemas/DataError' example: detail: Not authenticated DataForbidden: description: > Authenticated but not permitted. Three distinct causes: the session user is not invited (`Invite required`), the API key lacks the operation's scope, or API-key access to the requested venue is switched off (`API access is disabled for `). Admin and API-key callers bypass the invite check; session and admin callers bypass scope and venue checks. content: application/json: schema: $ref: '#/components/schemas/DataError' example: detail: Invite required 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.