> ## Documentation Index
> Fetch the complete documentation index at: https://docs.odds-api.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Historical Events

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



## OpenAPI

````yaml /api-reference/openapi.json get /historical/events
openapi: 3.0.0
info:
  description: >-
    Odds-API.io is a powerful sports betting odds comparison API, providing
    real-time data from 250+ bookmakers across 10+ sports with near zero
    latency.


    - 250+ bookmakers supported

    - 10+ 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
security: []
paths:
  /historical/events:
    get:
      tags:
        - Historical
      summary: Get Historical Events
      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.
      parameters:
        - description: API key for authentication
          name: apiKey
          in: query
          required: true
          schema:
            type: string
        - example: '"football"'
          description: Sport slug (e.g. football, basketball)
          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'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    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)
    controllers.ErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: Error message
    dto.League:
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
    dto.Score:
      type: object
      properties:
        away:
          type: integer
        home:
          type: integer
        periods:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/dto.PeriodScore'
    dto.Sport:
      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)
    dto.PeriodScore:
      type: object
      properties:
        away:
          type: integer
        home:
          type: integer

````