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

# Season Results

> Get all match results for a specific competition and season with standard pagination

# Season Results

Retrieve all completed match results for a specific competition season with standard page-based pagination.

<Warning>
  **Current Season Only**

  Due to the API data provider limitations, this endpoint only supports the **current season**. Historical season data (past seasons) is not accessible through the match results API.

  * **Current season requests** → Returns paginated match results ✅
  * **Historical season requests** → Returns 422 error with explanation ❌

  For historical data, the `/standings` endpoint provides final standings for previous seasons.
</Warning>

## Endpoint

```
GET /games/season-results
```

## Parameters

| Parameter      | Type    | Required | Description                                            |
| -------------- | ------- | -------- | ------------------------------------------------------ |
| `competitions` | number  | Yes      | Competition ID (e.g., 7 for Premier League)            |
| `seasonNum`    | number  | Yes      | Season number from `/standings?withSeasonsFilter=true` |
| `page`         | number  | No       | Page number (default: 1)                               |
| `pageSize`     | number  | No       | Results per page (default: 50, max: 100)               |
| `showOdds`     | boolean | No       | Include betting odds (default: false)                  |

## Discovering Season Numbers

Before using this endpoint, discover available seasons using the standings endpoint:

```bash theme={null}
curl -X GET "https://api.sportsapipro.com/v1/football/standings?competitions=7&withSeasonsFilter=true" \
  -H "x-api-key: YOUR_API_KEY"
```

The response includes a `seasonFilters` array:

```json theme={null}
{
  "seasonFilters": [
    { "num": 131, "name": "2025/26" },
    { "num": 130, "name": "2024/25" },
    { "num": 129, "name": "2023/24" },
    { "num": 128, "name": "2022/23" }
  ]
}
```

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.sportsapipro.com/v1/football/games/season-results?competitions=7&seasonNum=129&page=1&pageSize=100" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.sportsapipro.com/v1/football/games/season-results?competitions=7&seasonNum=129&page=1&pageSize=100',
    { headers: { 'x-api-key': 'YOUR_API_KEY' } }
  );
  const data = await response.json();
  console.log(`Page ${data.pagination.page}/${data.pagination.totalPages}`);
  console.log(`Total games: ${data.pagination.totalGames}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.sportsapipro.com/v1/football/games/season-results',
      params={'competitions': 7, 'seasonNum': 129, 'page': 1, 'pageSize': 100},
      headers={'x-api-key': 'YOUR_API_KEY'}
  )
  data = response.json()
  print(f"Page {data['pagination']['page']}/{data['pagination']['totalPages']}")
  print(f"Total games: {data['pagination']['totalGames']}")
  ```
</CodeGroup>

## Response Structure

```json theme={null}
{
  "seasonNum": 129,
  "seasonName": "2023/24",
  "competition": {
    "id": 7,
    "name": "Premier League",
    "countryId": 1
  },
  "pagination": {
    "page": 1,
    "pageSize": 100,
    "totalGames": 380,
    "totalPages": 4,
    "hasMore": true
  },
  "games": [
    {
      "id": 4567890,
      "competitionId": 7,
      "seasonNum": 129,
      "startTime": "2024-05-19T16:00:00+01:00",
      "statusGroup": 4,
      "homeCompetitor": {
        "id": 110,
        "name": "Manchester City",
        "score": 3
      },
      "awayCompetitor": {
        "id": 127,
        "name": "West Ham",
        "score": 1
      },
      "winner": 1
    }
  ],
  "competitors": [...],
  "countries": [...]
}
```

## Response Fields

| Field                   | Type    | Description                                  |
| ----------------------- | ------- | -------------------------------------------- |
| `seasonNum`             | number  | The requested season number                  |
| `seasonName`            | string  | Human-readable season name (e.g., "2023/24") |
| `competition`           | object  | Competition metadata (id, name, countryId)   |
| `pagination.page`       | number  | Current page number                          |
| `pagination.pageSize`   | number  | Results per page                             |
| `pagination.totalGames` | number  | Total games in the season                    |
| `pagination.totalPages` | number  | Total pages available                        |
| `pagination.hasMore`    | boolean | Whether more pages exist                     |
| `games`                 | array   | List of completed match results              |
| `competitors`           | array   | Team/competitor reference data               |
| `countries`             | array   | Country reference data                       |

## Complete Workflow: Fetch All Season Results

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function fetchFullSeasonResults(competitionId, seasonNum) {
    const allGames = [];
    let page = 1;
    let hasMore = true;
    
    while (hasMore) {
      const response = await fetch(
        `https://api.sportsapipro.com/v1/football/games/season-results?` +
        `competitions=${competitionId}&seasonNum=${seasonNum}&page=${page}&pageSize=100`,
        { headers: { 'x-api-key': 'YOUR_API_KEY' } }
      );
      const data = await response.json();
      
      allGames.push(...data.games);
      hasMore = data.pagination.hasMore;
      page++;
      
      console.log(`Page ${data.pagination.page}/${data.pagination.totalPages} - ${allGames.length} games`);
      
      // Rate limit: pause between requests
      await new Promise(r => setTimeout(r, 100));
    }
    
    console.log(`Total games: ${allGames.length}`);
    return allGames;
  }

  // Fetch all 380 Premier League games for 2023/24
  const results = await fetchFullSeasonResults(7, 129);
  ```

  ```python Python theme={null}
  import requests
  import time

  def fetch_full_season_results(competition_id, season_num):
      all_games = []
      page = 1
      has_more = True
      
      while has_more:
          response = requests.get(
              'https://api.sportsapipro.com/v1/football/games/season-results',
              params={
                  'competitions': competition_id,
                  'seasonNum': season_num,
                  'page': page,
                  'pageSize': 100
              },
              headers={'x-api-key': 'YOUR_API_KEY'}
          )
          data = response.json()
          
          all_games.extend(data['games'])
          has_more = data['pagination']['hasMore']
          page += 1
          
          print(f"Page {data['pagination']['page']}/{data['pagination']['totalPages']} - {len(all_games)} games")
          
          # Rate limit: pause between requests
          time.sleep(0.1)
      
      print(f"Total games: {len(all_games)}")
      return all_games

  # Fetch all Premier League games for 2023/24
  results = fetch_full_season_results(7, 129)
  ```
</CodeGroup>

## Multi-Season Historical Data

For analytics and prediction models requiring multiple seasons:

```javascript theme={null}
async function fetchMultiSeasonData(competitionId, numSeasons = 5) {
  // Step 1: Discover available seasons
  const standingsResponse = await fetch(
    `https://api.sportsapipro.com/v1/football/standings?competitions=${competitionId}&withSeasonsFilter=true`,
    { headers: { 'x-api-key': 'YOUR_API_KEY' } }
  );
  const standingsData = await standingsResponse.json();
  
  const seasons = standingsData.seasonFilters?.slice(0, numSeasons) || [];
  console.log(`Fetching ${seasons.length} seasons...`);
  
  const allData = {};
  
  for (const season of seasons) {
    console.log(`\nFetching ${season.name} (seasonNum: ${season.num})`);
    const games = await fetchFullSeasonResults(competitionId, season.num);
    allData[season.name] = games;
  }
  
  return allData;
}

// Fetch 5 seasons of Premier League data
const historicalData = await fetchMultiSeasonData(7, 5);
```

## Error Handling

| Status Code | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| 400         | Missing required parameters (`competitions` or `seasonNum`) |
| 401         | Invalid or missing API key                                  |
| 429         | Rate limit exceeded                                         |
| 500         | Server error                                                |

```json theme={null}
// 400 Error Response
{
  "error": "Missing required parameters",
  "message": "Both \"competitions\" and \"seasonNum\" parameters are required.",
  "example": "/games/season-results?competitions=7&seasonNum=129"
}
```

## Rate Limiting Notes

* Each call to `/games/season-results` counts as **1 API request** towards your daily quota
* The endpoint internally aggregates multiple internal calls, but you are only charged once
* For large datasets, add delays between paginated requests to avoid hitting rate limits
* A full Premier League season (380 games) requires 4 API calls at `pageSize=100`


## OpenAPI

````yaml GET /games/season-results
openapi: 3.1.0
info:
  title: SportsAPI Pro - Football API
  description: >-
    Professional football/soccer data API providing live scores, fixtures,
    statistics, betting odds, and more.
  version: 1.0.0
  contact:
    name: SportsAPI Pro Support
    email: support@sportsapipro.com
servers:
  - url: https://api.sportsapipro.com/v1/football
    description: Path-based front door (recommended)
  - url: https://v1.football.sportsapipro.com
    description: Classic per-sport vanity host
security:
  - ApiKeyAuth: []
paths:
  /games/season-results:
    get:
      tags:
        - Games
      summary: Season Results
      description: >-
        Get all match results for a specific competition and season with
        standard page-based pagination. Designed for bulk historical data
        ingestion and ETL pipelines.
      operationId: getSeasonResults
      parameters:
        - name: competitions
          in: query
          required: true
          description: Competition ID (e.g., 7 for Premier League)
          schema:
            type: integer
            example: 7
        - name: seasonNum
          in: query
          required: true
          description: >-
            Season number from /standings?withSeasonsFilter=true (e.g., 129 for
            2023/24)
          schema:
            type: integer
            example: 129
        - name: page
          in: query
          required: false
          description: 'Page number (default: 1)'
          schema:
            type: integer
            default: 1
            example: 1
        - name: pageSize
          in: query
          required: false
          description: 'Results per page (default: 50, max: 100)'
          schema:
            type: integer
            default: 50
            maximum: 100
            example: 100
        - name: showOdds
          in: query
          required: false
          description: 'Include betting odds data (default: false)'
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Season results retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  seasonNum:
                    type: integer
                    description: The requested season number
                  seasonName:
                    type: string
                    description: Human-readable season name (e.g., '2023/24')
                  competition:
                    type: object
                    description: Competition metadata
                    properties:
                      id:
                        type: integer
                      name:
                        type: string
                      countryId:
                        type: integer
                  pagination:
                    type: object
                    description: Pagination information
                    properties:
                      page:
                        type: integer
                        description: Current page number
                      pageSize:
                        type: integer
                        description: Results per page
                      totalGames:
                        type: integer
                        description: Total games in the season
                      totalPages:
                        type: integer
                        description: Total pages available
                      hasMore:
                        type: boolean
                        description: Whether more pages exist
                  games:
                    type: array
                    description: List of completed match results
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Game ID
                        competitionId:
                          type: integer
                        seasonNum:
                          type: integer
                        startTime:
                          type: string
                          description: ISO 8601 date/time
                        statusGroup:
                          type: integer
                          description: Status (4 = finished)
                        homeCompetitor:
                          type: object
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                            score:
                              type: integer
                        awayCompetitor:
                          type: object
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                            score:
                              type: integer
                        winner:
                          type: integer
                          description: 1 = home, 2 = away, 0 = draw
                  competitors:
                    type: array
                    description: Team/competitor reference data
                  countries:
                    type: array
                    description: Country reference data
        '400':
          description: 'Missing required parameters: competitions and seasonNum'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your SportsAPI Pro API key

````