Odds-API.io Historical API

openapi: 3.2.0
info:
  description: 'Odds-API.io is a powerful sports betting odds comparison API, providing real-time data from 450+ bookmakers across 34 sports with near zero latency.


    - 450+ bookmakers supported

    - 34 sports including Football, Basketball, Tennis, Esports and more

    - Real-time odds with close to zero latency

    - Pre-match & In-play odds coverage

    - 99.9% uptime for reliability'
  title: Odds-API.io - Real-Time Sports Betting Odds API (v3)…
  contact: {}
  version: 3.0.0
servers:
- url: https://api.odds-api.io/v3
tags:
- name: Historical
paths:
  /historical/events:
    get:
      security:
      - ApiKeyAuth: []
      description: Returns finished events for a given sport and league within a date range. Maximum date span is 31 days. Historical data is available from December 2025 onwards.
      tags:
      - Historical
      summary: Get Historical Events
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - example: '"football"'
        description: Sport name or slug (e.g. Football or football)
        name: sport
        in: query
        required: true
        schema:
          type: string
      - example: '"england-premier-league"'
        description: League slug (e.g. england-premier-league)
        name: league
        in: query
        required: true
        schema:
          type: string
      - example: '"2026-01-01T00:00:00Z"'
        description: Start date in RFC3339 format
        name: from
        in: query
        required: true
        schema:
          type: string
      - example: '"2026-01-31T23:59:59Z"'
        description: End date in RFC3339 format
        name: to
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/dto.SimpleEventDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: Get finished events for a sport and league in a date range of up to 31 days, to feed historical odds requests. Data is available from December 2025.
      operationId: getHistoricalEvents
      x-operation-id-source: derived
  /historical/events/search:
    get:
      security:
      - ApiKeyAuth: []
      description: Searches finished events by team name across all leagues, optionally scoped to a sport. Maximum date span is 31 days (defaults to the trailing 31 days). Returns up to 100 events, newest first. Historical data is available from December 2025 onwards.
      tags:
      - Historical
      summary: Search Historical Events
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - example: '"Brann"'
        description: Team name fragment, minimum 3 characters
        name: query
        in: query
        required: true
        schema:
          type: string
      - example: '"football"'
        description: Sport name or slug (e.g. Football or football)
        name: sport
        in: query
        required: false
        schema:
          type: string
      - example: '"2026-01-01T00:00:00Z"'
        description: Start date in RFC3339 format
        name: from
        in: query
        required: false
        schema:
          type: string
      - example: '"2026-01-31T23:59:59Z"'
        description: End date in RFC3339 format
        name: to
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/dto.SimpleEventDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: Search finished events by team name across all leagues, optionally by sport, over up to 31 days. Returns up to 100 events, newest first, since Dec 2025.
      operationId: getHistoricalEventsSearch
      x-operation-id-source: derived
  /historical/odds:
    get:
      security:
      - ApiKeyAuth: []
      description: Returns closing odds for a finished event from selected bookmakers, including scores.
      tags:
      - Historical
      summary: Get Historical Odds
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - example: '"123456"'
        description: Event ID from /historical/events
        name: eventId
        in: query
        required: true
        schema:
          type: string
      - example: '"Bet365,SingBet"'
        description: Comma-separated list of bookmaker names (max 30)
        name: bookmakers
        in: query
        required: true
        schema:
          type: string
      - example: '"ML,Totals"'
        description: Comma-separated market names to return (e.g. ML,Totals). Returns all markets when omitted.
        name: markets
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.EventResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: Get closing odds for a finished event from the bookmakers you choose, with final scores included. Filter by market to pull closing lines for backtesting.
      operationId: getHistoricalOdds
      x-operation-id-source: derived
  /historical/closing-lines:
    get:
      security:
      - ApiKeyAuth: []
      description: Returns closing odds for every settled event across one or more leagues in a date range, in a single request. Paid plans only.
      tags:
      - Historical
      summary: Get Historical Closing Lines
      parameters:
      - description: API key for authentication
        name: apiKey
        in: query
        required: true
        schema:
          type: string
      - example: '"football"'
        description: Sport name or slug (e.g. Football or football)
        name: sport
        in: query
        required: true
        schema:
          type: string
      - example: '"england-premier-league,spain-laliga"'
        description: Comma-separated league slugs (max 10)
        name: leagues
        in: query
        required: true
        schema:
          type: string
      - example: '"2026-01-01T00:00:00Z"'
        description: Start date in RFC3339 format
        name: from
        in: query
        required: true
        schema:
          type: string
      - example: '"2026-12-31T23:59:59Z"'
        description: End date in RFC3339 format. Maximum 366 days after from, so a full season fits in one sweep.
        name: to
        in: query
        required: true
        schema:
          type: string
      - example: '"ML,Totals"'
        description: Comma-separated market names
        name: markets
        in: query
        required: true
        schema:
          type: string
      - example: '"Bet365,Unibet"'
        description: Comma-separated list of bookmaker names (max 30)
        name: bookmakers
        in: query
        required: true
        schema:
          type: string
      - example: 100
        description: Maximum number of events to return. Every response is capped at 100; use limit + skip to paginate.
        name: limit
        in: query
        required: false
        schema:
          type: integer
      - example: 0
        description: Number of events to skip (for pagination)
        name: skip
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/controllers.EventResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ErrorResponse'
      x-mint:
        metadata:
          description: Get closing odds for every settled event across one or more leagues in a date range in a single request, filtered by market and bookmaker. Paid plans only.
      operationId: getHistoricalClosingLines
      x-operation-id-source: derived
components:
  schemas:
    dto.SideFloats:
      type: object
      description: 'Home/away pair that can be fractional. Cricket overs use cricket notation: 19.3 means nineteen overs and three balls.'
      properties:
        away:
          type: number
          example: 20
        home:
          type: number
          example: 20
    dto.MultiMarketDto:
      type: object
      properties:
        name:
          type: string
        odds:
          type: array
          items:
            $ref: '#/components/schemas/dto.Odds'
        updatedAt:
          type: string
    dto.PeriodScore:
      type: object
      properties:
        away:
          type: integer
        home:
          type: integer
        overs:
          allOf:
          - $ref: '#/components/schemas/dto.SideFloats'
          description: Cricket only. Overs bowled by each side in this innings.
        wickets:
          allOf:
          - $ref: '#/components/schemas/dto.SideInts'
          description: Cricket only. Wickets lost by each side in this innings.
    dto.EsportsDto:
      type: object
      description: Present on esports events only
      properties:
        game:
          allOf:
          - $ref: '#/components/schemas/dto.Sport'
          description: 'The game being played, e.g. {"name": "Valorant", "slug": "valorant"}'
        league:
          allOf:
          - $ref: '#/components/schemas/dto.League'
          description: Parent league (VCT, LCK, LEC). Its slug stays the same across the league's splits and stages.
        region:
          description: 'Region of the tournament: Western Europe, Eastern Europe, North America, South America, Asia, Oceania or Middle East. Omitted when unknown.'
          type: string
          example: Western Europe
        format:
          allOf:
          - $ref: '#/components/schemas/dto.EsportsFormatDto'
          description: Match format. Omitted when unknown.
    dto.EsportsFormatDto:
      type: object
      properties:
        type:
          description: bestOf or firstTo
          type: string
          example: bestOf
        games:
          description: 'Number of games: 3 for a best of 3'
          type: integer
          example: 3
    controllers.Sport:
      type: object
      properties:
        name:
          type: string
          example: Football
        slug:
          type: string
          example: football
    dto.Score:
      type: object
      properties:
        away:
          type: integer
        home:
          description: 'Headline result: includes overtime, never a penalty shootout.'
          type: integer
        periods:
          description: Keyed p1..pN (that period only), ft, ot and ap (running totals after regulation, overtime and a penalty shootout), currentgame, mapN, inningN. See https://docs.odds-api.io/guides/live-events#period-scores
          type: object
          additionalProperties:
            $ref: '#/components/schemas/dto.PeriodScore'
    dto.Sport:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
    controllers.EventResponse:
      type: object
      properties:
        away:
          type: string
        awayId:
          type: integer
        bookmakerIds:
          type: object
          additionalProperties:
            type: string
        bookmakers:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/dto.MultiMarketDto'
        date:
          type: string
        home:
          type: string
        homeId:
          type: integer
        id:
          type: integer
        league:
          $ref: '#/components/schemas/controllers.League'
        scores:
          $ref: '#/components/schemas/dto.Score'
        sport:
          $ref: '#/components/schemas/controllers.Sport'
        status:
          description: 'Whether the match is under way: pending, live, settled or cancelled. Can read live before the listed start, or while /events still lists the event as pending. A pending event never carries in-play prices.'
          type: string
        urls:
          type: object
          additionalProperties:
            type: string
    dto.SideInts:
      type: object
      description: Home/away pair of whole numbers (cricket wickets).
      properties:
        away:
          type: integer
          example: 9
        home:
          type: integer
          example: 6
    controllers.ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Error message
    dto.Odds:
      type: object
      properties:
        '12':
          type: string
        1X:
          description: 'Specialty market fields

            Double Chance: 1X (home or draw), 12 (home or away), X2 (draw or away)'
          type: string
        X2:
          type: string
        away:
          type: string
        awayLink:
          type: string
        depthAway:
          type: string
        depthDraw:
          type: string
        depthHome:
          type: string
        depthLayAway:
          type: string
        depthLayDraw:
          type: string
        depthLayHome:
          type: string
        depthLayNo:
          description: Available liquidity to lay no. Yes/no markets only (currently Both Teams To Score on exchange-style books).
          type: string
        depthLayOver:
          description: Available liquidity to lay over. On yes/no markets this repeats depthLayYes, kept for compatibility.
          type: string
        depthLayUnder:
          description: Available liquidity to lay under. On yes/no markets this repeats depthLayNo, kept for compatibility.
          type: string
        depthLayYes:
          description: Available liquidity to lay yes. Yes/no markets only (currently Both Teams To Score on exchange-style books).
          type: string
        depthNo:
          description: Available liquidity to back no. Yes/no markets only (currently Both Teams To Score on exchange-style books).
          type: string
        depthOver:
          description: Available liquidity to back over. On yes/no markets this repeats depthYes, kept for compatibility.
          type: string
        depthUnder:
          description: Available liquidity to back under. On yes/no markets this repeats depthNo, kept for compatibility.
          type: string
        depthYes:
          description: Available liquidity to back yes. Yes/no markets only (currently Both Teams To Score on exchange-style books).
          type: string
        draw:
          type: string
        drawLink:
          type: string
        even:
          type: string
        exactly:
          description: 'Three-way corner lines only (Corners, Alternative Corners, 1st Half Corners): price for the count landing exactly on hdp. When present, Over and Under both lose on that number.'
          type: string
        hdp:
          type: number
        home:
          type: string
        homeLink:
          type: string
        label:
          type: string
        layAway:
          type: string
        layDraw:
          type: string
        layHome:
          type: string
        layNo:
          type: string
        layOver:
          type: string
        layUnder:
          type: string
        layYes:
          type: string
        max:
          type: integer
        neither:
          description: 'Corners Race: neither team reaches the target'
          type: string
        'no':
          type: string
        none:
          description: 'First Team To Score: none option'
          type: string
        odd:
          description: Odd/Even market
          type: string
        odds:
          description: Labeled markets (Half Time / Full Time, Correct Score) - single odds value per outcome
          type: string
        over:
          type: string
        under:
          type: string
        'yes':
          type: string
    controllers.League:
      type: object
      properties:
        name:
          type: string
          example: Premier League
        slug:
          type: string
          example: premier-league
    dto.SimpleEventDto:
      type: object
      properties:
        away:
          type: string
        awayId:
          type: integer
        bookmakerCount:
          type: integer
        date:
          type: string
        home:
          type: string
        homeId:
          type: integer
        id:
          type: integer
        league:
          $ref: '#/components/schemas/dto.League'
        scores:
          $ref: '#/components/schemas/dto.Score'
        sport:
          $ref: '#/components/schemas/dto.Sport'
        status:
          type: string
        clock:
          allOf:
          - $ref: '#/components/schemas/dto.ClockDto'
          description: Live match clock (live events only; absent when no clock data is available)
        esports:
          allOf:
          - $ref: '#/components/schemas/dto.EsportsDto'
          description: 'Esports events only: game, parent league, region and match format'
    dto.League:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
    dto.ClockDto:
      type: object
      description: Live match-clock state for in-play events. minute/playedSeconds are extrapolated server-side from the live feed and only advance while running is true.
      properties:
        minute:
          type: integer
          example: 67
          description: Current match minute
        playedSeconds:
          type: integer
          example: 4023
          description: Seconds of play elapsed
        period:
          type: integer
          example: 2
          description: Current period number
        running:
          type: boolean
          example: true
          description: Whether the clock is currently running
        statusDetail:
          type: string
          example: 2nd half
          description: Human-readable phase of play
        serve:
          type: string
          enum:
          - home
          - away
          description: Current server (tennis, table tennis, volleyball)
        injuryTime:
          type: integer
          example: 4
          description: Announced injury/stoppage time in minutes (football)
        periodStartedAt:
          type: integer
          example: 1792170000
          description: 'Unix timestamp (seconds) when the current period started. Sent only when the feed has no played clock (for example ice hockey games with basic coverage), never alongside playedSeconds. Wall time, not game time: a stopped clock makes the elapsed wall time longer than the time played, so never treat it as playedSeconds. Omitted when the value is missing, in the future, or more than 3 hours old. Also present in WebSocket clock snapshots.'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apiKey
      description: Your Odds-API.io API key, sent as the apiKey query parameter. Get one at https://odds-api.io/pricing.
x-origin:
- url: https://api.odds-api.io/v3/docs/doc.json
  format: swagger
  version: '2.0'
  converter:
    url: https://github.com/mermade/oas-kit
    version: 7.0.8