> ## 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 an aggregated analysis of a squad

> Calculate the expected league rank, total expected transfer fee and total future transfer value of a squad. The squad can optionally be provided by the user

The `POST /squad_analysis`  endpoint calculates the total expected transfer fee and total future transfer value of a squad, by taking the sum of these values for each player in the squad. Furthermore, it calculates the expected end rank in the club's competition with the given squad.

If no squad is provided, the endpoint assumes the current real life squad for the provided club. However, the user can provide a squad object in the request. Players can be removed from the squad or added with their assumed position. This way, the user can easily simulate the effect of certain transfers (not) happening. For stable competition simulations, it's advised to only perform minor perturbations on existing squads and keep provided squads realistic and balanced.

<Note>
  The analysis is always run against the **2026/2027 season**. Season is not yet a request parameter. The `club_id` must be club inside your coverage. Contact SquadAssist to adjust access.
</Note>

<Note>
  The squad object used for the calculations is echoed in the response. The user can do the first request without providing a squad, and start from the echoed default squad object for 'what if' analysis.
</Note>

## Request

The request body must be a JSON object.

<ParamField body="club_id" type="string" required>
  The SquadAssist club ID for the club. Contact SquadAssist to confirm which club IDs are available on your plan. Use `POST /query_club` to look up the ID.
</ParamField>

<ResponseField name="squad" type="list[object]">
  Echo of the assumed squad during the simulations and calculations of the request. If no squad is provided by the user, returns the actual squad of the club.

  <Expandable title="squad player object">
    <ParamField body="name" type="string">
      The name of the player.

      <ParamField body="player_id" type="string">
        The SquadAssist player\_id of the player.

        <ParamField body="position" type="string">
          The assumed position of the player within the squad.
        </ParamField>
      </ParamField>
    </ParamField>
  </Expandable>
</ResponseField>

<ParamField body="currency_code" type="string">
  An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code (e.g. `EUR`, `GBP`, `USD`). All input amounts (`annual_wage`, `expected_transfer_value`) are interpreted in this currency. Defaults to `EUR`.
</ParamField>

## Response

The response is a JSON object containing each component of the squad analysis. All monetary values are provided in both the requested currency and EUR.

<ResponseField name="club_id" type="string">
  The SquadAssist club ID for the club.
</ResponseField>

<ResponseField name="currency" type="string">
  The ISO 4217 currency code used for all non-EUR monetary values in the response. Matches your `currency_code` input, or `EUR` if none was provided.
</ResponseField>

<ResponseField name="expected_league_rank" type="integer">
  The expected rank for the club in its current domestic league and season.
</ResponseField>

<ResponseField name="squad" type="list[object]">
  Echo of the assumed squad during the simulations and calculations of the request. If no squad is provided by the user, returns the actual squad of the club.

  <Expandable title="squad player object">
    <ParamField body="name" type="string">
      The name of the player.

      <ParamField body="player_id" type="string">
        The SquadAssist player\_id of the player.

        <ParamField body="position" type="string">
          The assumed position of the player within the squad.
        </ParamField>
      </ParamField>
    </ParamField>
  </Expandable>
</ResponseField>

<ResponseField name="squad_size" type="integer">
  The amount of players in the squad used in this request.
</ResponseField>

<ResponseField name="squad_source" type="string">
  Flag to indicate whether the user has provided a squad, or the calculations used the actual squad of the club. Value is either "custom" or "actual"
</ResponseField>

<ResponseField name="total_expected_transfer_fee" type="int">
  The sum of the expected transfer fee of all players in the squad, in the requested currency.
</ResponseField>

<ResponseField name="total_expected_transfer_fee_in_eur" type="int">
  The sum of the expected transfer fee of all players in the squad, in euro.
</ResponseField>

<ResponseField name="total_future_transfer_value" type="int">
  The sum of the future transfer value (in 3 years) of all players in the squad, in the requested currency.
</ResponseField>

<ResponseField name="total_future_transfer_value_in_eur" type="int">
  The sum of the future transfer value (in 3 years) of all players in the squad, in euro.
</ResponseField>

## Example

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

  $body = @{
      "club_id": "C01JJBVJAPKG8CM7ZA5JF5G84R8",
       "squad": [
          {
              "name": "Bentayeb",
              "player_id": "P01JV8C4DF8BSRTXKE7RB6KKQ0Z",
              "position": "CF"
          },
          {
              "name": "Hey",
              "player_id": "P01JJ9QA71Q083H1Y7AXVGWW6DE",
              "position": "CB"
          },
          {
              "name": "Reabciuk",
              "player_id": "P01JJ9Q8XW27JRK24TB4SQN2DJ0",
              "position": "LWB"
          },
          {
              "name": "Degreef",
              "player_id": "P01JJ9QAFCM13KE1TY4QAC9MR7F",
              "position": "CAM"
          },
  		...
      ]
  }

  Invoke-RestMethod -Uri "https://api.squadassist.ai/v1/squad_analysis" `
                    -Method Post `
                    -Headers $headers `
                    -Body ($body | ConvertTo-Json)
  ```

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

  # 1. Define the endpoint
  url = "https://api.squadassist.ai/v1/squad_analysis"

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

  # 3. Define the data (equivalent to the PowerShell $body)
  payload = {
      "club_id": "C01JJBVJAPKG8CM7ZA5JF5G84R8",
       "squad": [
          {
              "name": "Bentayeb",
              "player_id": "P01JV8C4DF8BSRTXKE7RB6KKQ0Z",
              "position": "CF"
          },
          {
              "name": "Hey",
              "player_id": "P01JJ9QA71Q083H1Y7AXVGWW6DE",
              "position": "CB"
          },
          {
              "name": "Reabciuk",
              "player_id": "P01JJ9Q8XW27JRK24TB4SQN2DJ0",
              "position": "LWB"
          },
          {
              "name": "Degreef",
              "player_id": "P01JJ9QAFCM13KE1TY4QAC9MR7F",
              "position": "CAM"
          },
  		...
      ]
  }

  # 4. Make the POST request
  response = requests.post(url, headers=headers, json=payload)

  # 5. Output the result
  if response.status_code == 200:
      data = response.json()
      print("Success!")
      print(data)
  else:
      print(f"Error {response.status_code}: {response.text}")
  ```
</CodeGroup>

<CodeGroup>
  ```json Response theme={null}
  {
      "club_id": "C01JJBVJAPKG8CM7ZA5JF5G84R8",
      "currency": "EUR",
      "expected_league_rank": 1.72,
      "squad": [
          {
              "name": "Bentayeb",
              "player_id": "P01JV8C4DF8BSRTXKE7RB6KKQ0Z",
              "position": "CF"
          },
          {
              "name": "Hey",
              "player_id": "P01JJ9QA71Q083H1Y7AXVGWW6DE",
              "position": "CB"
          },
          {
              "name": "Reabciuk",
              "player_id": "P01JJ9Q8XW27JRK24TB4SQN2DJ0",
              "position": "LWB"
          },
          {
              "name": "Degreef",
              "player_id": "P01JJ9QAFCM13KE1TY4QAC9MR7F",
              "position": "CAM"
          },
          {
              "name": "Omobamidele",
              "player_id": "P01JJ9Q9TEJW48TBDDHEAJFYXZE",
              "position": "CB"
          },
          {
              "name": "Aasgaard",
              "player_id": "P01JSQC8TBNBGWWVF8PAVBYRT7V",
              "position": "CAM"
          },
          {
              "name": "Amané",
              "player_id": "P01K0WQ9VGD4K4RCK0C6963059K",
              "position": "CM"
          },
          {
              "name": "Koutsoupias",
              "player_id": "P01K0WPPXXJJ8JAYSRA8SSSJXXP",
              "position": "CM"
          },
          {
              "name": "Augustinsson",
              "player_id": "P01JJ9Q5X1SP796X0PP3SEK116E",
              "position": "LB"
          },
          {
              "name": "Kana",
              "player_id": "P01JJ9Q93BBDY8Z03GEX8NPD1TF",
              "position": "CM"
          },
          {
              "name": "Koïté",
              "player_id": "P01M1W12FJNXGY09N04P72T6QVF",
              "position": "LB"
          },
          {
              "name": "Biancone",
              "player_id": "P01JJ9Q9C2RP29JPJW2J2A9SMAA",
              "position": "CB"
          },
          {
              "name": "Coosemans",
              "player_id": "P01JJ9Q5NPSNFNWAB4ZD8AEHCW6",
              "position": "GK"
          },
          {
              "name": "Stroeykens",
              "player_id": "P01JJ9Q9NC8VA9TJ4WXTQ8N9D9M",
              "position": "CAM"
          },
          {
              "name": "Pétrot",
              "player_id": "P01JJ9Q8KF69HJPXSC3YSE8F3ZC",
              "position": "CB"
          },
          {
              "name": "Maamar",
              "player_id": "P01K0WPQJNZR0SB2FMS3Y5HP96E",
              "position": "RB"
          },
          {
              "name": "Ede Eriyo",
              "player_id": "P01KWHX7PG85QR0N6YN158B0M7J",
              "position": "RW"
          },
          {
              "name": "Mujangi Bia",
              "player_id": "P01KWHX7PHK1GPQCK201KPE4EBF",
              "position": "CDM"
          },
          {
              "name": "Kagé",
              "player_id": "P01KWHX7PM8T7J7T7N76G06C3M5",
              "position": "LW"
          },
          {
              "name": "Vekeman",
              "player_id": "P01KWHX7PNJPF6MXKB703RY1M24",
              "position": "GK"
          },
          {
              "name": "Van de Ven",
              "player_id": "P01K0WQD9VX6HEAYYEM1VSG1WRM",
              "position": "CF"
          },
          {
              "name": "De Ridder",
              "player_id": "P01K0WQD9WD6EJ8YYQ5G04SQTQC",
              "position": "CM"
          },
          {
              "name": "Mahroug",
              "player_id": "P01K0WQD9YC6PECGJ547S981YR1",
              "position": "LB"
          },
          {
              "name": "Nga Kana",
              "player_id": "P01K26ZB2Q88X0X2BB52BDQ7SRV",
              "position": "LW"
          },
          {
              "name": "Hungenaert",
              "player_id": "P01KBFKN0M3SNVPT33FRGP5QQPD",
              "position": "CB"
          },
          {
              "name": "Camara",
              "player_id": "P01JV8C49ZKYXXR82JSDH6Y4036",
              "position": "RWB"
          },
          {
              "name": "Putu",
              "player_id": "P01K0WQD9YWWQFZBP1TCH4B1VRW",
              "position": "RB"
          },
          {
              "name": "Cvetković",
              "player_id": "P01K26ZB2NFFR10QK70TQFWVZ75",
              "position": "CF"
          },
          {
              "name": "Sarr",
              "player_id": "P01KHRMZARBE1W906V4MJ79ECTF",
              "position": "CM"
          },
          {
              "name": "Engwanda",
              "player_id": "P01K0WPQJM1R81VN2T8E52JQA3G",
              "position": "CB"
          },
          {
              "name": "Ambros",
              "player_id": "P01JJ9QA1BB0REANGF19E84Q0YM",
              "position": "RW"
          },
          {
              "name": "Flips",
              "player_id": "P01JJ9Q8E96C41580VKDN0W1X1Q",
              "position": "CAM"
          },
          {
              "name": "Llansana",
              "player_id": "P01JJ9Q8KK4C581EJC84KR9XZ6B",
              "position": "CM"
          },
          {
              "name": "Sikan",
              "player_id": "P01JJ9Q8MBNQCDZM64CVYCTNTPE",
              "position": "CF"
          },
          {
              "name": "Heekeren",
              "player_id": "P01JJ9Q8W593FBJPG858M3TWMYW",
              "position": "GK"
          },
          {
              "name": "Bertaccini",
              "player_id": "P01JJ9R7M05JT8JCKM786J1TCK2",
              "position": "CF"
          },
          {
              "name": "Sardella",
              "player_id": "P01JJ9Q8WBEHZ1RX69NA6168JJC",
              "position": "RB"
          },
          {
              "name": "Antman",
              "player_id": "P01JJ9Q9AHKM102WRVYPXCXXAAB",
              "position": "LW"
          },
          {
              "name": "Barry",
              "player_id": "P01K0WQD9NEEARBAEHK6W3P3ZB0",
              "position": "CB"
          },
          {
              "name": "Keita",
              "player_id": "P01JV8C4Y8F5A00EBVAZNCT8K6T",
              "position": "CB"
          },
          {
              "name": "Onia Seke",
              "player_id": "P01K26ZQA5HBHB3TDCVDE11FB62",
              "position": "RW"
          },
          {
              "name": "Winkler",
              "player_id": "P01JJ9Q9K7WNKBV5G23QZHCBQE4",
              "position": "RW"
          }
      ],
      "squad_size": 42,
      "squad_source": "actual",
      "total_expected_transfer_fee": 89645328,
      "total_expected_transfer_fee_in_eur": 89645328,
      "total_future_transfer_value": 138810554,
      "total_future_transfer_value_in_eur": 138810554
  }
  ```
</CodeGroup>

## Errors

| Status | Body | Cause |
| - | - | - |
| `400` | `{"error": "club_id is required"}` | `club_id` was not included in the request body |
| `400` | `{"error": "Invalid club_id"}` | The `club_id` format is not valid |
| `400` | `{"error": "currency_code must be a string"}` | `currency_code` was provided but is not a string |
| `403` | `{ "error": "Duplicate player_id in squad: P01JJ9Q705Y8NGDA243DV28HX36" }`<br />`{ "error": "squad[2]: Invalid position 'STRIKER'. Must be one of: CAM, CB, ..." }`<br />`{ "error": "squad must contain at least 11 players (got 8)" } ` | Malformed squad object in the request body. |
| `403` | `{ "error": "The requested team does not match the team linked to this account." }` | The `club_id` is not available on your plan |
| `404` | `{"error": "Club not found"}` | No club was found for the provided `club_id` |


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