Athlete Game History

Get game history for a specific athlete with summary display stats

GET /athletes/games

Player Game Logs

cURL

curl --request GET \
  --url https://v1.basketball.sportsapipro.com/athletes/games \
  --header 'x-api-key: <api-key>'

Endpoint

GET https://v1.football.sportsapipro.com/athletes/games

Description

Retrieves the game history for a specific athlete with summary display statistics. This endpoint is useful for building player career pages and tracking game appearances.

Summary Stats Only: This endpoint returns basic display stats (jersey number, match result indicator), not detailed performance metrics. For granular per-game stats like shots, tackles, and xG, use the /athletes/games/lineups endpoint.

Built-in TTL: 60 seconds. Game history is cached for efficient repeated queries.

Parameters

Parameter	Type	Required	Default	Description
athleteId	number	Yes	-	The unique identifier of the athlete (also accepts athletes)
numOfGames	number	No	50	Maximum number of games to return

Both athleteId and athletes parameter names are supported. The API accepts either for convenience.

Request Examples

cURL

curl -X GET "https://v1.football.sportsapipro.com/athletes/games?athleteId=73000&numOfGames=10" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "lastUpdateId": 5494796687,
  "requestedUpdateId": -1,
  "ttl": 60,
  "games": [
    {
      "id": 4609054,
      "sportId": 1,
      "competitionId": 572,
      "competitionDisplayName": "UEFA Champions League",
      "seasonNum": 25,
      "stageNum": 1,
      "roundNum": 8,
      "roundName": "Round of 16",
      "homeCompetitorId": 131,
      "awayCompetitorId": 84,
      "statusGroup": 4,
      "statusText": "Ended",
      "shortStatusText": "FT",
      "gameTime": 90,
      "startTime": "2025-03-11T20:00:00+00:00",
      "homeCompetitorScore": 3,
      "awayCompetitorScore": 1,
      "played": true,
      "athleteStats": [
        { "type": 229, "value": "9", "logo": false },
        { "type": 0, "value": "-", "logo": false }
      ]
    }
  ],
  "sports": [...],
  "countries": [...],
  "competitions": [...],
  "competitors": [...]
}

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 (60 for this endpoint)
games	array	Array of game objects with athlete summary stats
sports	array	Sports definitions for matched entities
countries	array	Countries referenced by games
competitions	array	Competitions referenced by games
competitors	array	Teams referenced by games

Game Object

Field	Type	Description
id	number	Unique game ID
sportId	number	Sport ID (1 = Football)
competitionId	number	Competition ID
competitionDisplayName	string	Full competition name
seasonNum	number	Season number
stageNum	number	Stage number within competition
roundNum	number	Round number
roundName	string	Human-readable round name
homeCompetitorId	number	Home team ID
awayCompetitorId	number	Away team ID
statusGroup	number	Game status group (4 = Ended)
statusText	string	Human-readable status
shortStatusText	string	Short status (FT, HT, etc.)
gameTime	number	Current/final game time in minutes
startTime	string	ISO 8601 kickoff time
homeCompetitorScore	number	Home team score
awayCompetitorScore	number	Away team score
played	boolean	Whether athlete played in this game
athleteStats	array	Summary display stats (see below)

athleteStats Array

The athleteStats field contains an array of summary display statistics with numeric type IDs:

Type ID	Description
229	Jersey number
0	Match result indicator / rating
27	Goals (when available)
26	Assists (when available)

{
  "athleteStats": [
    { "type": 229, "value": "9", "logo": false },
    { "type": 0, "value": "7.2", "logo": false }
  ]
}

Empty Stats Objects

The athleteStats array may contain empty objects {} for stats with zero values. This is by design - stat types are omitted when the value is zero to reduce response size.

Example Response with Zero Values:

{
  "athleteStats": [
    { "type": 229, "value": "9" },    // Jersey number
    {},                                // Goals = 0 (omitted)
    {},                                // Assists = 0 (omitted)  
    { "type": 0, "value": "6.8" }     // Rating
  ]
}

Solution: Always check for empty objects when parsing:

// Safe extraction pattern
const athleteStats = game.athleteStats || [];

const goals = athleteStats.find(s => s.type === 27)?.value || 0;
const assists = athleteStats.find(s => s.type === 26)?.value || 0;
const rating = athleteStats.find(s => s.type === 0)?.value || 'N/A';
const jerseyNumber = athleteStats.find(s => s.type === 229)?.value;

For more details on handling empty responses, see our Troubleshooting Guide.

Need Detailed Stats? For comprehensive per-game metrics like shots, tackles, xG, pass accuracy, and 40+ other stats, use the two-step workflow below.

Getting Detailed Player Stats

The /athletes/games endpoint provides summary data. For detailed performance metrics, combine it with /athletes/games/lineups:

// Step 1: Get player's recent games
const gamesResponse = await fetch(
  'https://v1.football.sportsapipro.com/athletes/games?athleteId=73000&numOfGames=5',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const { games } = await gamesResponse.json();

// Step 2: Get detailed stats for each game
for (const game of games) {
  const lineupsResponse = await fetch(
    `https://v1.football.sportsapipro.com/athletes/games/lineups?athleteId=73000&gameId=${game.id}`,
    { headers: { 'x-api-key': 'YOUR_API_KEY' } }
  );
  const lineups = await lineupsResponse.json();
  
  // Access detailed stats from lineups.members[0].stats
  // Stats include: shots (type 3), tackles (type 39), xG (type 76), etc.
}

The lineups endpoint returns 40+ detailed metrics including:

• Shots (type 3), Shots on Target (type 4)
• Tackles Won (type 39), Interceptions (type 41)
• Expected Goals (type 76), Pass Accuracy
• Minutes Played, Match Rating, and more

Use Cases

Player Career Page

// Fetch last 50 games for a player's career page
const { games } = await getAthleteGames(athleteId, 50);

// Count appearances by competition
const appearancesByCompetition = games.reduce((acc, game) => {
  const compName = game.competitionDisplayName;
  acc[compName] = (acc[compName] || 0) + 1;
  return acc;
}, {});

Recent Form Widget

// Get last 5 games for form indicator
const response = await fetch(
  `https://v1.football.sportsapipro.com/athletes/games?athleteId=73000&numOfGames=5`,
  { headers: { "x-api-key": "YOUR_API_KEY" } }
);
const { games } = await response.json();

// Display W/D/L indicators based on scores
const formIndicators = games.map(g => {
  const isHome = g.athleteStats.some(s => s.type === 229); // played
  // Determine result based on scores
  return g.homeCompetitorScore > g.awayCompetitorScore ? 'W' : 
         g.homeCompetitorScore < g.awayCompetitorScore ? 'L' : 'D';
});

Error Responses

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

{
  "error": "Missing required parameter: athleteId"
}

Authorizations

x-api-key · string · header · required

Your SportsAPI Pro API key

Query Parameters

athleteId · integer · required

Player ID

Example:

12345

numOfGames · integer · default: 10

Number of games to return

Example:

10

Response

200

Player game logs retrieved successfully