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

# Athlete Season Stats

> Get season-by-season statistics for an athlete in a specific competition

## Endpoint

```
GET https://api.sportsapipro.com/v1/football/athletes/trophies/stats
```

## Description

Retrieves comprehensive season-by-season statistics for a specific athlete, optionally filtered by competition. This endpoint provides historical performance data essential for career analysis, season comparisons, and statistical breakdowns.

<Info>
  Built-in TTL: **300 seconds** (5 minutes). Season statistics are cached longer as they change less frequently.
</Info>

## Parameters

| Parameter       | Type   | Required | Default | Description                           |
| --------------- | ------ | -------- | ------- | ------------------------------------- |
| `athleteId`     | number | Yes      | -       | The unique identifier of the athlete  |
| `competitionId` | number | Yes\*    | -       | The competition to retrieve stats for |

<Warning>
  **`competitionId` is effectively required.** While technically optional, omitting it will return empty data (`"No data available"`) for most athletes. Always provide a `competitionId` to get results.
</Warning>

<Note>
  Common competition IDs: Premier League (`7`), La Liga (`104`), Serie A (`17`), Bundesliga (`199`), Ligue 1 (`176`), Champions League (`572`).
</Note>

## Request Examples

<CodeGroup>
  ```bash cURL theme={null}
  # Get stats for athlete in a specific competition
  curl -X GET "https://api.sportsapipro.com/v1/football/athletes/trophies/stats?athleteId=874&competitionId=104" \
    -H "x-api-key: YOUR_API_KEY"

  # Get all competition stats for an athlete
  curl -X GET "https://api.sportsapipro.com/v1/football/athletes/trophies/stats?athleteId=874" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  // Specific competition
  const response = await fetch(
    `https://api.sportsapipro.com/v1/football/athletes/trophies/stats?athleteId=874&competitionId=104`,
    {
      headers: { "x-api-key": "YOUR_API_KEY" }
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://api.sportsapipro.com/v1/football/athletes/trophies/stats",
      params={
          "athleteId": 874,
          "competitionId": 104
      },
      headers={"x-api-key": "YOUR_API_KEY"}
  )
  data = response.json()
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "lastUpdateId": 5494796687,
  "requestedUpdateId": -1,
  "ttl": 300,
  "stats": {
    "columns": [
      { "id": "season", "name": "Season", "type": "string" },
      { "id": "appearances", "name": "Apps", "type": "number" },
      { "id": "goals", "name": "Goals", "type": "number" },
      { "id": "assists", "name": "Assists", "type": "number" },
      { "id": "yellowCards", "name": "YC", "type": "number" },
      { "id": "redCards", "name": "RC", "type": "number" },
      { "id": "minutesPlayed", "name": "Mins", "type": "number" },
      { "id": "avgRating", "name": "Avg Rating", "type": "number" }
    ],
    "rows": [
      {
        "season": "2024/25",
        "seasonNum": 25,
        "competitionId": 104,
        "competitionName": "La Liga",
        "appearances": 28,
        "goals": 22,
        "assists": 14,
        "yellowCards": 3,
        "redCards": 0,
        "minutesPlayed": 2340,
        "avgRating": 8.2
      },
      {
        "season": "2023/24",
        "seasonNum": 24,
        "competitionId": 104,
        "competitionName": "La Liga",
        "appearances": 35,
        "goals": 26,
        "assists": 16,
        "yellowCards": 5,
        "redCards": 0,
        "minutesPlayed": 2980,
        "avgRating": 8.4
      }
    ]
  },
  "athletes": [...],
  "competitions": [...],
  "sports": [...]
}
```

## Response Fields

### Root Object

| Field               | Type   | Description                                    |
| ------------------- | ------ | ---------------------------------------------- |
| `lastUpdateId`      | number | Internal versioning ID for incremental updates |
| `requestedUpdateId` | number | Requested update ID (-1 = latest)              |
| `ttl`               | number | Cache TTL in seconds (300 for this endpoint)   |
| `stats`             | object | Statistics container with columns and rows     |
| `athletes`          | array  | Athlete information                            |
| `competitions`      | array  | Competition definitions                        |
| `sports`            | array  | Sport definitions                              |

### Stats Object

| Field     | Type  | Description                                  |
| --------- | ----- | -------------------------------------------- |
| `columns` | array | Column definitions for interpreting row data |
| `rows`    | array | Season-by-season statistical data            |

### Column Object

| Field  | Type   | Description                   |
| ------ | ------ | ----------------------------- |
| `id`   | string | Column identifier             |
| `name` | string | Human-readable column name    |
| `type` | string | Data type: "string", "number" |

### Row Object (Season Stats)

| Field             | Type   | Description                           |
| ----------------- | ------ | ------------------------------------- |
| `season`          | string | Season display name (e.g., "2024/25") |
| `seasonNum`       | number | Numeric season identifier             |
| `competitionId`   | number | Competition ID                        |
| `competitionName` | string | Competition name                      |
| `appearances`     | number | Total appearances                     |
| `goals`           | number | Goals scored                          |
| `assists`         | number | Assists provided                      |
| `yellowCards`     | number | Yellow cards received                 |
| `redCards`        | number | Red cards received                    |
| `minutesPlayed`   | number | Total minutes played                  |
| `avgRating`       | number | Average match rating (1.0-10.0)       |

## Use Cases

### Career Statistics Table

```javascript theme={null}
// Fetch all-time stats across competitions
const response = await fetch(
  `https://api.sportsapipro.com/v1/football/athletes/trophies/stats?athleteId=874`,
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);

const { stats } = await response.json();

// Render a data table using columns for headers
const headers = stats.columns.map(col => col.name);
const rows = stats.rows.map(row => 
  stats.columns.map(col => row[col.id])
);
```

### Season Comparison Chart

```javascript theme={null}
// Compare goal output across seasons
const goalsBySeasonData = stats.rows.map(row => ({
  season: row.season,
  goals: row.goals,
  assists: row.assists
}));

// Use with charting library
<BarChart data={goalsBySeasonData} />
```

### Multi-Competition Career Summary

```javascript theme={null}
// Fetch stats for multiple competitions concurrently
const competitionIds = [104, 572, 596]; // La Liga, UCL, Copa del Rey

const statsPromises = competitionIds.map(compId =>
  fetch(`https://api.sportsapipro.com/v1/football/athletes/trophies/stats?athleteId=874&competitionId=${compId}`, 
    { headers: { "x-api-key": "YOUR_API_KEY" } }
  ).then(r => r.json())
);

const allStats = await Promise.all(statsPromises);
```

## Error Responses

| Status | Description                            |
| ------ | -------------------------------------- |
| 400    | Missing required `athleteId` parameter |
| 401    | Invalid or missing API key             |
| 429    | Rate limit exceeded                    |
| 500    | Internal server error                  |

```json theme={null}
{
  "error": "Missing required parameter: athleteId"
}
```


## OpenAPI

````yaml GET /athletes/trophies/stats
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:
  /athletes/trophies/stats:
    get:
      tags:
        - Athletes
      summary: Athlete Season Stats
      description: >-
        Get season-by-season statistics for an athlete, optionally filtered by
        competition
      operationId: getAthleteTrophiesStats
      parameters:
        - name: athleteId
          in: query
          required: true
          description: The unique identifier of the athlete
          schema:
            type: integer
            example: 874
        - name: competitionId
          in: query
          required: false
          description: Filter stats to a specific competition
          schema:
            type: integer
            example: 104
      responses:
        '200':
          description: Athlete season statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  stats:
                    type: object
                    properties:
                      columns:
                        type: array
                        description: Column definitions for data interpretation
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            type:
                              type: string
                      rows:
                        type: array
                        description: Season-by-season data
                        items:
                          type: object
                          properties:
                            season:
                              type: string
                            seasonNum:
                              type: integer
                            competitionId:
                              type: integer
                            competitionName:
                              type: string
                            appearances:
                              type: integer
                            goals:
                              type: integer
                            assists:
                              type: integer
                            yellowCards:
                              type: integer
                            redCards:
                              type: integer
                            minutesPlayed:
                              type: integer
                            avgRating:
                              type: number
                  athletes:
                    type: array
                  competitions:
                    type: array
        '400':
          description: 'Missing required parameter: athleteId'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your SportsAPI Pro API key

````