> ## Documentation Index > Fetch the complete documentation index at: https://docs.oddspapi.io/llms.txt > Use this file to discover all available pages before exploring further. # 历史赔率 > 获取赛事的历史赔率时间线。 查询模式：必需 `fixtureId` + （未提供 `oddsIds` 时必需 `bookmaker`）或 `oddsIds`。 ## OpenAPI ````yaml /zh/api-reference/openapi.json get /fixtures/odds/historical openapi: 3.1.0 info: title: 赔率 API v5 version: 5.0.0 description: 高性能赔率API，由Valkey + Supabase RPC发现支持。 servers: - url: https://v5.oddspapi.io/zh security: - ApiKeyAuth: [] - ApiKeyHeaderAuth: [] tags: - name: common - name: fixtures - name: fixtures/odds - name: parlays - name: futures - name: futures/odds - name: mapping - name: media - name: settlement paths: /fixtures/odds/historical: get: tags: - fixtures/odds summary: 历史赔率 description: |- 获取赛事的历史赔率时间线。 查询模式：必需 `fixtureId` + （未提供 `oddsIds` 时必需 `bookmaker`）或 `oddsIds`。 operationId: fixtures_odds_historical__lang__fixtures_odds_historical_get parameters: - $ref: '#/components/parameters/fixtureIdStringRequired' - name: bookmaker in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Single bookmaker slug. RULE: If oddsIds is NOT provided, you must pass exactly ONE bookmaker. - name: oddsIds in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Optional: comma/space-separated oddsIds to restrict the response.' responses: '200': description: >- Returns FixtureHistoricalOddsResponse (fixture meta + time-series odds) content: application/json: schema: $ref: '#/components/schemas/FixtureHistoricalOddsResponse' examples: example: summary: Historical odds value: fixtureId: id1400003160574219 reissuedFixtureId: null status: live: false statusId: 2 statusName: Finished sport: sportId: 14 sportName: American Football tournament: tournamentId: 31 tournamentName: NFL categoryName: USA season: seasonId: null seasonName: null seasonRound: null venue: venueId: null venueName: null venueLocation: null startTime: 1766685600 trueStartTime: '2025-12-25T18:00:17.744256+00:00' trueEndTime: '2025-12-25T21:09:09.345372+00:00' participants: participant1Id: 4423 participant1RotNr: null participant1Name: Minnesota Vikings participant1ShortName: Vikings participant1Abbr: null participant2Id: 4419 participant2RotNr: null participant2Name: Detroit Lions participant2ShortName: Lions participant2Abbr: null scores: {} clock: currentPeriod: null currentTime: null remainingTime: null remainingTimeInPeriod: null stopped: null expectedPeriods: 4 periodLength: 15 externalProviders: {} odds: bet365: id1400003160574219:bet365:14198:0: '1765975761422': bookmaker: bet365 outcomeId: 14198 playerId: 0 price: 1.952 active: true changedAt: 1765975761422 marketActive: true '1766361894121': bookmaker: bet365 outcomeId: 14198 playerId: 0 price: 1.952 active: true changedAt: 1766361894121 marketActive: true '400': $ref: '#/components/responses/ApiError' '401': $ref: '#/components/responses/ApiError' '403': $ref: '#/components/responses/ApiError' '404': $ref: '#/components/responses/ApiError' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/ApiError' components: parameters: fixtureIdStringRequired: name: fixtureId in: query required: true schema: type: string description: Single fixture ID (e.g. id1400003160574219). schemas: FixtureHistoricalOddsResponse: allOf: - $ref: '#/components/schemas/Fixture' - type: object properties: odds: $ref: '#/components/schemas/HistoricalOddsByBookmaker' required: - odds additionalProperties: true Fixture: type: object properties: fixtureId: type: string description: 赛事标识符：`{prefix}{sportId}{tournamentId}{nativeId}` —— 参见核心概念 → ID 结构。 reissuedFixtureId: type: - string - 'null' description: >- 当一场被取消的赛事以新的 id 重新上架时，这里是替代它的那场赛事。`null` 才是常态：只有在赛事已被取消（`status.statusId` 为 `3`）且替代赛事确实已出现在数据流中时才会被填充，因此永久性取消会一直保持 `null`，而一场赛事也可能在您首次看到它被取消之后才从 `null` 变为具体的 id。只指向一跳：若该替代赛事本身也被取消，请继续跟随它自己的 `reissuedFixtureId`。 status: $ref: '#/components/schemas/Status' description: 赛事的生命周期状态。 sport: $ref: '#/components/schemas/SportRef' description: 运动引用。 tournament: $ref: '#/components/schemas/TournamentRef' description: 锦标赛引用。 season: $ref: '#/components/schemas/SeasonRef' description: 赛季引用（如已解析）。 venue: $ref: '#/components/schemas/VenueRef' description: 场馆引用（如已知）。 startTime: type: integer description: Epoch seconds (UTC). trueStartTime: type: - string - 'null' description: 实际开始时间（ISO 8601，一旦已知）—— 可能与计划的 `startTime` 不同。 trueEndTime: type: - string - 'null' description: 实际结束时间（ISO 8601，一旦已知）。 participants: $ref: '#/components/schemas/ParticipantsRef' description: 双方参赛者，含名称、轮转号和缩写。 scores: type: object additionalProperties: $ref: '#/components/schemas/ScorePeriod' description: 按赛段键组织的比分行（`result`、`p1`……）。 clock: anyOf: - $ref: '#/components/schemas/Clock' - type: 'null' description: 比赛进行中的实时计时。 expectedPeriods: type: - integer - 'null' description: 该赛事预期的常规赛段数 —— 结合 `periodLength` 用于按运动/联赛解读赛段键。 periodLength: type: - integer - 'null' description: 常规赛段的时长（分钟）。 externalProviders: $ref: '#/components/schemas/ExternalProviders' description: 该赛事在外部数据源（betradar、pinnacle 等）的原生标识符。 bookmakers: type: object additionalProperties: $ref: '#/components/schemas/BookmakerFixtureMeta' description: >- 该赛事按博彩公司划分的可用性与新鲜度元数据。仅包含当前为该赛事提供有效实时赔率的博彩公司。在赛事和赔率端点中返回；在 CLV、历史赔率和结算响应中省略。 required: - fixtureId - reissuedFixtureId - status - sport - tournament - season - venue - startTime - participants - scores - clock - externalProviders additionalProperties: true HistoricalOddsByBookmaker: type: object additionalProperties: type: object additionalProperties: type: object additionalProperties: $ref: '#/components/schemas/OddQuote' Error: type: object description: Concrete error format returned by this API (no FastAPI detail wrapper). properties: error: type: integer description: HTTP status code message: type: string description: Human-readable error message details: description: Optional extra details (string/object/array depending on the error). reason: type: string deprecated: true description: '**已弃用**，`code` 的别名，请改读 `code`。' code: type: string description: 机器可读的原因代码。 required: - error - message additionalProperties: true HTTPValidationError: title: HTTPValidationError type: object properties: detail: title: Detail type: array items: $ref: '#/components/schemas/ValidationError' description: 校验错误列表。 Status: type: object properties: live: type: boolean description: 便捷标志 —— 仅在比赛进行中为 true（`statusId` 为 1）。 statusId: type: integer description: 生命周期状态：`0` 赛前、`1` 进行中、`2` 已结束、`3` 已取消。只会向前推进 —— 请始终基于此 ID 做分支判断。 statusName: type: string description: 状态的翻译显示标签。业务逻辑请基于 `statusId` 判断，切勿依赖此字符串。 required: - live - statusId - statusName additionalProperties: true SportRef: type: object properties: sportId: type: integer description: 数字运动标识符。 sportName: type: string description: 运动显示名称，跟随请求的语言前缀翻译。 required: - sportId - sportName additionalProperties: true TournamentRef: type: object properties: tournamentId: type: integer description: 数字锦标赛标识符。 tournamentName: type: string description: 锦标赛显示名称，跟随请求的语言前缀翻译。 categoryName: type: - string - 'null' description: 类别（通常是国家/地区）显示名称，已翻译。 required: - tournamentId - tournamentName additionalProperties: true SeasonRef: type: object properties: seasonId: type: - integer - 'null' description: 数字赛季标识符（如已知）。 seasonName: type: - string - 'null' description: 赛季显示名称，已翻译。 seasonRound: type: - integer - 'null' description: 赛季内的轮次编号（如适用）。 additionalProperties: true VenueRef: type: object properties: venueId: type: - integer - 'null' description: 数字场馆标识符（如已知）。 venueName: type: - string - 'null' description: 场馆显示名称，已翻译。 venueLocation: type: - string - 'null' description: 场馆所在地（城市），已翻译。 additionalProperties: true ParticipantsRef: type: object properties: participant1Id: type: integer description: 参赛者 1（主队 / 先列一方）的标识符。 participant1RotNr: type: - integer - 'null' description: 参赛者 1 的轮转号（美式盘口惯例，如有）。 participant1Name: type: - string - 'null' description: 参赛者 1 的全名，已翻译。 participant1ShortName: type: - string - 'null' description: 参赛者 1 的短名称。 participant1Abbr: type: - string - 'null' description: 参赛者 1 的缩写。 participant2Id: type: integer description: 参赛者 2（客队 / 后列一方）的标识符。 participant2RotNr: type: - integer - 'null' description: 参赛者 2 的轮转号（美式盘口惯例，如有）。 participant2Name: type: - string - 'null' description: 参赛者 2 的全名，已翻译。 participant2ShortName: type: - string - 'null' description: 参赛者 2 的短名称。 participant2Abbr: type: - string - 'null' description: 参赛者 2 的缩写。 required: - participant1Id - participant2Id additionalProperties: true ScorePeriod: type: object properties: period: type: string description: 该比分行对应的赛段键（`result` = 总比分；参见枚举页）。 participant1Score: type: integer description: 参赛者 1 在该赛段的得分。 participant2Score: type: integer description: 参赛者 2 在该赛段的得分。 updatedAt: type: string description: 该比分值最近一次变化的时间。 required: - period - participant1Score - participant2Score - updatedAt additionalProperties: true Clock: type: object properties: currentPeriod: type: - string - 'null' description: 当前正在进行的赛段键（参见枚举页的赛段词汇表）。 currentTime: type: - string - 'null' description: 比赛已进行时间，`mm:ss`。 remainingTime: type: - string - 'null' description: 比赛剩余时间，`mm:ss`（倒计时类运动）。 remainingTimeInPeriod: type: - string - 'null' description: 当前赛段剩余时间，`mm:ss`。 stopped: type: - boolean - 'null' description: 比赛计时暂停时为 true。 additionalProperties: true ExternalProviders: type: object additionalProperties: true BookmakerFixtureMeta: type: object properties: bookmaker: type: string description: 博彩公司标识。 bookmakerFixtureId: type: - string - 'null' description: 该赛事在博彩公司的原生标识符。 fixturePath: type: - string - 'null' description: 该赛事在博彩公司网站上的页面路径（如已知）。 hasOdds: type: boolean description: 博彩公司当前是否为该赛事发布赔率。 staleOdds: type: boolean description: 交易关键字段：与该博彩公司的连接丢失或中断时为 true，此时无法再保证赔率的新鲜度。 staleOddsResponseCode: type: - integer - 'null' deprecated: true description: '**已弃用。** 陈旧检测期间观察到的 HTTP 状态码（如有）。请改用 `staleOdds`。' suspended: type: boolean description: 博彩公司暂停该赛事投注时为 true。 participantsRotated: type: boolean description: 如果博彩公司列出的参赛者顺序与 OddsPapi 相反（参赛者 1/2 互换）则为 true。 meta: type: - object - 'null' additionalProperties: true description: 博彩公司特定的元数据。 updatedAt: type: string description: 该博彩公司元数据最近一次变化的时间。 required: - bookmaker - hasOdds - staleOdds - suspended - participantsRotated - updatedAt additionalProperties: true OddQuote: type: object properties: bookmaker: type: string description: 博彩公司标识。 outcomeId: type: integer description: 该投注选项的冻结结果标识符。 playerId: type: integer description: 价格对应的球员；非球员盘口为 `0`。 price: type: number description: 十进制（欧洲）赔率。 active: type: boolean description: 该结果当前在博彩公司是否可投注。 marketActive: type: - boolean - 'null' description: 整个盘口在博彩公司是否处于激活状态。 mainLine: type: - boolean - 'null' description: 是否为博彩公司在该盘口类型下的主盘口线。 marketId: type: integer description: 该结果所属的冻结盘口标识符。 bookmakerMarketId: type: - string - 'null' description: 博彩公司的原生盘口标识符。 bookmakerOutcomeId: type: - string - 'null' description: 博彩公司的原生结果标识符。 bookmakerChangedAt: type: - integer - 'null' description: 博彩公司提供的变更时间戳（毫秒，如有）。 priceFractional: type: - string - 'null' description: 分数赔率（如 `5/2`）。 priceAmerican: type: - integer - 'null' description: 美式赔率（如 `-110`、`+250`）。 meta: type: - object - 'null' description: 博彩公司特定的元数据（订单簿、赔率阶梯等）。 limit: type: - number - 'null' description: 博彩公司提供的最大可接受投注额（如有）。 betslip: type: - string - 'null' description: 博彩公司投注单 / 深链接令牌（如有）。 changedAt: type: integer description: OddsPapi 在博彩商处观察到此变更的时间（毫秒，UTC）—— 始终存在。 required: - bookmaker - outcomeId - playerId - price - active - changedAt additionalProperties: true ValidationError: title: ValidationError type: object required: - loc - msg - type properties: loc: title: Location type: array items: anyOf: - type: string - type: integer description: 无效参数的位置（路径片段）。 msg: title: Message type: string description: 人类可读的校验信息。 type: title: Error Type type: string description: 机器可读的错误类型。 responses: ApiError: description: API error content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_filters: summary: Invalid filters value: error: 400 message: Invalid filters. reason: invalid_filters invalid_api_key: summary: Invalid apiKey value: error: 401 message: invalid apiKey reason: invalid_api_key rate_limited: summary: Rate limited value: error: 429 message: rate limit exceeded reason: rate_limited retryAfterSec: 1 ValidationError: description: Validation Error (framework-level) content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' securitySchemes: ApiKeyAuth: type: apiKey in: query name: apiKey description: 作为 `apiKey` 查询参数传入的 API 密钥。 ApiKeyHeaderAuth: type: apiKey in: header name: X-API-Key description: 作为 `X-API-Key` 请求头传入的 API 密钥。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.