Take full control of your simulation and predict anything.
Use the /simulate endpoint when you want full manual control over the simulation context, including the exact lineup of your team and the exact lineup of every opponent.
Unlike /simulate_fast, which automatically generates lineups for you, the /simulate endpoint gives you complete freedom to define any tactical setup, any player configuration, and any contextual player arrangement.
This endpoint is ideal when:
you want to simulate custom team structures,
evaluate your own predicted lineups,
test hypothetical scenario planning,
or run research experiments where full control is required.
🔧 Request Body Parameters
simulation_id: str, A unique identifier for this simulation.
competition_name: str, Name of the competition in which the simulation takes place.
team_name: str, The name of the team you are simulating.
team_lineup: List[PlayerInfo], A manually defined list of PlayerInfo dataclass instances representing your team’s lineup.
This lineup must include the players you want to simulate, in the positions and contextual roles you choose.
A PlayerInfo object typically includes:
player_id: str — the BALLER unique player ID
player_name: str
position: str — one of
["GK", "CB", "LB", "RB", "WB", "DF", "CM", "DM", "AM", "LM", "RM", "MF", "FW", "LW", "RW"]
minutes: int, the number of minutes played you want to simulate, between 1 and 90.
team: str, the team in which you want to simulate your player.
combined_stat_label: int, a unique performance label (only for the teammates, not for the simulated players) .
You have full freedom to define any team structure.
players_to_simulate: List[SimPlayerInfo]
A list of SimPlayerInfo objects describing the players for whom you want performance predictions.
This works exactly as in /simulate_fast and includes:
player_id: str
player_name: str
position: str
minutes: int
team: str — team where the player is simulated (normally team_name)
These attributes ensure extreme granularity, giving you precise control over how the model interprets each player in context.
opponent_lineups: List[List[PlayerInfo]]
A list of opponent lineups. Each opponent lineup is itself a list of PlayerInfo objects describing the full squad of the opposing team.
This lets you craft:
custom opponent structures,
modified tactical shapes,
simulated hypothetical transfers,
“what-if” scenarios based on your own data.
🧠 How It Works
The /simulate endpoint runs the exact same inference engine as /simulate_fast, but without automatic lineup generation. Instead, the simulation is performed directly on the lineups you provide.
Example
Eze and Gyokeres with Arsenal, against Newcastle United and Tottenham in the Premier League
Inputs
Outputs
Each entry contains:
the opponent name
the simulated performance outputs for the player(s) of interest
all generated metrics (binned stats, label probabilities, readable ranges, etc.)