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

# GET /playing_time — Get Player Playing Time

> Returns a player's minutes, appearances, and starts, grouped by season and then by competition and club. Includes domestic league, domestic cup, international cup, international supercup, and senior national team.

## Authentication

All requests must include a valid API key, either as an `x-api-key` header or as a Bearer token in the `Authorization` header.

```http theme={null}
x-api-key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY
```

## Request

<ParamField query="player_id" type="string" required>
  The SquadAssist player ID. Obtain this from `POST /query_player` if you only have an external ID such as a Transfermarkt or Wyscout ID.
</ParamField>

<ParamField query="season" type="string">
  Limit the response to one season. Format `YYYY/YYYY`, for example `2025/2026`. When omitted, every available season is returned, newest first.
</ParamField>

## Response

Matches the player did not play are excluded. Youth national team, friendlies, youth competitions, reserves, and domestic supercups are omitted. A player who represented two clubs in the same competition in one season gets one entry per club.

<ResponseField name="player_id" type="string">
  Echoes the `player_id` from the request.
</ResponseField>

<ResponseField name="seasons" type="array">
  One object per season, newest season first.

  <Expandable title="Season">
    <ResponseField name="season" type="string">
      Season label in `YYYY/YYYY` format.
    </ResponseField>

    <ResponseField name="competitions" type="array">
      One object per competition and club in that season. Ordered by competition type, then competition id, then club name.

      <Expandable title="Competition">
        <ResponseField name="competition" type="string">
          Competition identifier, for example `BELGIAN_JUPILER_PRO_LEAGUE`.
        </ResponseField>

        <ResponseField name="competition_name" type="string">
          Display name of the competition, for example `Belgian Jupiler Pro League`.
        </ResponseField>

        <ResponseField name="competition_type" type="string">
          One of `DOMESTIC_LEAGUE`, `DOMESTIC_CUP`, `INTERNATIONAL_CUP`, `INTERNATIONAL_SUPERCUP`, or `NATIONAL_TEAM`. For `NATIONAL_TEAM`, `club_id` and `club_name` refer to the senior national team.
        </ResponseField>

        <ResponseField name="club_id" type="string">
          SquadAssist id of the club, or of the national team for a `NATIONAL_TEAM` entry.
        </ResponseField>

        <ResponseField name="club_name" type="string">
          Display name of that club or national team.
        </ResponseField>

        <ResponseField name="minutes_played" type="int">
          Total minutes played in this competition for this club during the season.
        </ResponseField>

        <ResponseField name="appearances" type="int">
          Number of matches played in this competition for this club during the season.
        </ResponseField>

        <ResponseField name="starting_xi_count" type="int">
          Number of those appearances in which the player started.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
  ```bash Powershell theme={null}
  $headers = @{
      "x-api-key"    = "your API key" #Change 
      "Content-Type" = "application/json"
  }

  #Change player_id in request to desired player 
  curl "https://api.squadassist.ai/v1/playing_time?player_id=P01K0WPQJPWZCNCYH1KXHTJ9R31" -H $headers
  ```

  ```python Python theme={null}
      # 1. Define the endpoint with the player_id already in the URL
      url = "https://api.squadassist.ai/v1/playing_time"
      player_id = "P01K0WPQJPWZCNCYH1KXHTJ9R31" # Change 

      # 2. Set up your headers
      headers = {
          "x-api-key": API_KEY, # Replace with your actual key
          "Content-Type": "application/json"
      }

      # 3. Add the parameters
      params = {
          "player_id": player_id 
      }

      # 4. Make the GET request
      response = requests.get(url, headers=headers, params=params)
      # 5. Output the result
      if response.status_code == 200:
          data = response.json()
          print(data)
      else:
          print(f"Error {response.status_code}: {response.text}")
  ```

  ```r R theme={null}
  library(httr2)

  # 1. Define the base URL and the API key
  base_url <- "https://api.squadassist.ai/v1/playing_time"
  api_key  <- "API_KEY"

  # 2. Build the request
  req <- httr2::request(base_url) |>
    httr2::req_headers("x-api-key" = API_KEY) |>
    # This adds the ?player_id=... part automatically
    httr2::req_url_query(player_id = "P01K0WPQJPWZCNCYH1KXHTJ9R31")

  # 3. Perform and parse
  resp <- httr2::req_perform(req)
  player_info <- httr2::resp_body_json(resp)

  print(player_info)
  ```
</CodeGroup>

The JSON below shows the response shape for the same player as the career path example. A senior national-team competition uses the same object, with the national team as `club_id` and `club_name`.

```json Response theme={null}
{
    "player_id": "P01K0WPQJPWZCNCYH1KXHTJ9R31",
    "seasons": [
        {
            "season": "2026/2027",
            "competitions": [
                {
                    "competition": "GERMAN_1_BUNDESLIGA",
                    "competition_name": "German 1 Bundesliga",
                    "competition_type": "DOMESTIC_LEAGUE",
                    "club_id": "C01JJBWJRY350A4XZN1G1YN2MBP",
                    "club_name": "TSG 1899 Hoffenheim",
                    "minutes_played": 180,
                    "appearances": 2,
                    "starting_xi_count": 2
                }
            ]
        },
        {
            "season": "2025/2026",
            "competitions": [
                {
                    "competition": "BELGIAN_CUP",
                    "competition_name": "Belgian Cup",
                    "competition_type": "DOMESTIC_CUP",
                    "club_id": "C01JJBVJAPKG8CM7ZA5JF5G84R8",
                    "club_name": "RSC Anderlecht",
                    "minutes_played": 90,
                    "appearances": 1,
                    "starting_xi_count": 1
                },
                {
                    "competition": "BELGIAN_JUPILER_PRO_LEAGUE",
                    "competition_name": "Belgian Jupiler Pro League",
                    "competition_type": "DOMESTIC_LEAGUE",
                    "club_id": "C01JJBVJAPKG8CM7ZA5JF5G84R8",
                    "club_name": "RSC Anderlecht",
                    "minutes_played": 2430,
                    "appearances": 28,
                    "starting_xi_count": 26
                },
                {
                    "competition": "EUROPA_LEAGUE",
                    "competition_name": "Europa League",
                    "competition_type": "INTERNATIONAL_CUP",
                    "club_id": "C01JJBVJAPKG8CM7ZA5JF5G84R8",
                    "club_name": "RSC Anderlecht",
                    "minutes_played": 540,
                    "appearances": 6,
                    "starting_xi_count": 6
                }
            ]
        }
    ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.