# SofaScore API

> SofaScore returns football match and player season data, available as a workflow and API.

SofaScore returns football match scores, incidents, team statistics, and player ratings from two team names and an optional date. Get player season stats returns a football player’s season statistics from a player name and optional competition and season.

- Page: https://fous.com/tools/sofascore
- Handle: `@sofascore`
- Category: [Sports](https://fous.com/tools/category/sports)
- Source website: https://sofascore.com
- Last verified: Sep 29, 2026

## Methods

### Get match

Operation `get_match`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get a football match’s score, incidents, team statistics and player ratings from two team names. Without a date, returns their most recent played or live match; some matches do not have all statistics or ratings.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `date` | string | no | `"2025-10-26"` | Match date in YYYY-MM-DD, for example 2025-10-26. Omit for the latest played or live match. |
| `team_1` | string | yes | `"Barcelona"` | First football team, for example Barcelona. |
| `team_2` | string | yes | `"Real Madrid"` | Second football team, for example Real Madrid. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "team_1",
    "team_2"
  ],
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "Match date in YYYY-MM-DD, for example 2025-10-26. Omit for the latest played or live match.",
      "examples": [
        "2025-10-26"
      ]
    },
    "team_1": {
      "type": "string",
      "description": "First football team, for example Barcelona.",
      "examples": [
        "Barcelona"
      ]
    },
    "team_2": {
      "type": "string",
      "description": "Second football team, for example Real Madrid.",
      "examples": [
        "Real Madrid",
        "Atlético Madrid"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "team_1": "Barcelona",
      "team_2": "Real Madrid"
    },
    {
      "date": "2025-10-26",
      "team_1": "Barcelona",
      "team_2": "Real Madrid"
    },
    {
      "team_1": "Barcelona",
      "team_2": "Atlético Madrid"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `goals` | array |  |  |
| `goals[].team` | string | `"FC Barcelona"` |  |
| `goals[].assist` | string or null | `"Dani Olmo"` |  |
| `goals[].minute` | string or null | `"9"` |  |
| `goals[].scorer` | string or null | `"Marcus Rashford"` |  |
| `score` | object |  |  |
| `score.away` | integer or null | `0` |  |
| `score.home` | integer or null | `2` |  |
| `venue` | string or null | `"Spotify Camp Nou"` |  |
| `status` | string or null | `"Ended"` |  |
| `players` | array |  |  |
| `players[].name` | string | `"Joan García"` |  |
| `players[].team` | string | `"FC Barcelona"` |  |
| `players[].rating` | number or null | `7.2` |  |
| `players[].position` | string or null | `"Goalkeeper"` |  |
| `players[].player_id` | integer or null | `930267` |  |
| `players[].minutes_played` | integer or null | `90` |  |
| `event_id` | integer | `14083562` |  |
| `away_team` | string | `"Real Madrid"` |  |
| `date_time` | string | `"2026-05-10T19:00:00+00:00"` |  |
| `home_team` | string | `"FC Barcelona"` |  |
| `red_cards` | array |  |  |
| `red_cards[].team` | string | `"Real Madrid"` |  |
| `red_cards[].minute` | string or null | `"-5"` |  |
| `red_cards[].player` | string or null | `"Andriy Lunin"` |  |
| `red_cards[].reason` | string or null | `"Red card"` |  |
| `away_stats` | object |  |  |
| `away_stats.team` | string | `"Real Madrid"` |  |
| `away_stats.fouls` | number or null | `9` |  |
| `away_stats.passes` | number or null | `394` |  |
| `away_stats.corners` | number or null | `8` |  |
| `away_stats.total_shots` | number or null | `8` |  |
| `away_stats.expected_goals` | number or null | `0.85` |  |
| `away_stats.shots_on_target` | number or null | `1` |  |
| `away_stats.possession_percent` | number or null | `43` |  |
| `away_stats.pass_accuracy_percent` | number or null | `86.5` |  |
| `home_stats` | object |  |  |
| `home_stats.team` | string | `"FC Barcelona"` |  |
| `home_stats.fouls` | number or null | `18` |  |
| `home_stats.passes` | number or null | `529` |  |
| `home_stats.corners` | number or null | `4` |  |
| `home_stats.total_shots` | number or null | `10` |  |
| `home_stats.expected_goals` | number or null | `1.01` |  |
| `home_stats.shots_on_target` | number or null | `7` |  |
| `home_stats.possession_percent` | number or null | `57` |  |
| `home_stats.pass_accuracy_percent` | number or null | `91.9` |  |
| `match_link` | string | `"https://www.sofascore.com/football/match/real-madrid-barcelona/rgbsEgb#id:14083562"` |  |
| `competition` | string or null | `"LaLiga"` |  |
| `half_time_score` | object |  |  |
| `half_time_score.away` | integer or null | `0` |  |
| `half_time_score.home` | integer or null | `2` |  |

**Example input**

```json
{
  "team_1": "Barcelona",
  "team_2": "Real Madrid"
}
```

**Example output**

```json
{
  "goals": [
    {
      "team": "FC Barcelona",
      "assist": null,
      "minute": "9",
      "scorer": "Marcus Rashford"
    },
    {
      "team": "FC Barcelona",
      "assist": "Dani Olmo",
      "minute": "18",
      "scorer": "Ferran Torres"
    }
  ],
  "score": {
    "away": 0,
    "home": 2
  },
  "venue": "Spotify Camp Nou",
  "status": "Ended",
  "players": [
    {
      "name": "Joan García",
      "team": "FC Barcelona",
      "rating": 7.2,
      "position": "Goalkeeper",
      "player_id": 930267,
      "minutes_played": 90
    },
    {
      "name": "Eric García",
      "team": "FC Barcelona",
      "rating": 6.9,
      "position": "Defender",
      "player_id": 876214,
      "minutes_played": 90
    },
    {
      "name": "Pau Cubarsí",
      "team": "FC Barcelona",
      "rating": 7.5,
      "position": "Defender",
      "player_id": 1402913,
      "minutes_played": 90
    }
  ],
  "event_id": 14083562,
  "away_team": "Real Madrid",
  "date_time": "2026-05-10T19:00:00+00:00",
  "home_team": "FC Barcelona",
  "red_cards": [],
  "away_stats": {
    "team": "Real Madrid",
    "fouls": 9,
    "passes": 394,
    "corners": 8,
    "total_shots": 8,
    "expected_goals": 0.85,
    "shots_on_target": 1,
    "possession_percent": 43,
    "pass_accuracy_percent": 86.5
  },
  "home_stats": {
    "team": "FC Barcelona",
    "fouls": 18,
    "passes": 529,
    "corners": 4,
    "total_shots": 10,
    "expected_goals": 1.01,
    "shots_on_target": 7,
    "possession_percent": 57,
    "pass_accuracy_percent": 91.9
  },
  "match_link": "https://www.sofascore.com/football/match/real-madrid-barcelona/rgbsEgb#id:14083562",
  "competition": "LaLiga",
  "half_time_score": {
    "away": 0,
    "home": 2
  }
}
```

### Get player season stats

Operation `get_player_season_stats`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get a football player’s season statistics by name, with an optional competition and season. Unavailable statistics are null.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `player` | string | yes | `"Alisson"` | Football player name, for example Erling Haaland. |
| `season` | string | no | `"2025/26"` | Season, for example 2025/26. Defaults to the current season. |
| `competition` | string | no | `"Premier League"` | Competition name, for example Premier League. Defaults to the player’s main league. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "player"
  ],
  "properties": {
    "player": {
      "type": "string",
      "description": "Football player name, for example Erling Haaland.",
      "examples": [
        "Alisson",
        "Erling Haaland"
      ]
    },
    "season": {
      "type": "string",
      "default": "",
      "description": "Season, for example 2025/26. Defaults to the current season.",
      "examples": [
        "2025/26"
      ]
    },
    "competition": {
      "type": "string",
      "default": "",
      "description": "Competition name, for example Premier League. Defaults to the player’s main league.",
      "examples": [
        "Premier League"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "player": "Alisson"
    },
    {
      "player": "Erling Haaland",
      "season": "2025/26",
      "competition": "Premier League"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `age` | integer or null | `33` | Age in years. |
| `team` | string or null | `"Liverpool FC"` | Team for this competition and season. |
| `goals` | integer or null | `0` | Goals. |
| `saves` | integer or null | `14` | Saves for goalkeepers. |
| `player` | string or null | `"Alisson"` | Player name. |
| `season` | string or null | `"2026/27"` | Season used. |
| `starts` | integer or null | `5` | Matches started. |
| `assists` | integer or null | `0` | Assists. |
| `position` | string or null | `"Goalkeeper"` | Playing position. |
| `player_id` | integer or null | `243609` | SofaScore player ID. |
| `red_cards` | integer or null | `0` | Red cards. |
| `appearances` | integer or null | `5` | Appearances in the season. |
| `competition` | string or null | `"Premier League"` | Competition used. |
| `nationality` | string or null | `"Brazil"` | Country of nationality. |
| `clean_sheets` | integer or null | `3` | Clean sheets for goalkeepers. |
| `yellow_cards` | integer or null | `1` | Yellow cards. |
| `expected_goals` | number or null | `25.4326` | Expected goals. |
| `minutes_played` | integer or null | `450` | Minutes played. |
| `sofascore_link` | string or null | `"https://www.sofascore.com/football/player/alisson/243609"` | Player page link on SofaScore. |
| `photo_image_link` | string or null | `"https://img.sofascore.com/api/v1/player/243609/image"` | Player photo image link. |
| `average_sofascore_rating` | number or null | `7.36` | Average SofaScore rating from 0 to 10. |

**Example input**

```json
{
  "player": "Alisson"
}
```

**Example output**

```json
{
  "age": 33,
  "team": "Liverpool FC",
  "goals": 0,
  "saves": 14,
  "player": "Alisson",
  "season": "2026/27",
  "starts": 5,
  "assists": 0,
  "position": "Goalkeeper",
  "player_id": 243609,
  "red_cards": 0,
  "appearances": 5,
  "competition": "Premier League",
  "nationality": "Brazil",
  "clean_sheets": 3,
  "yellow_cards": 1,
  "expected_goals": null,
  "minutes_played": 450,
  "sofascore_link": "https://www.sofascore.com/football/player/alisson/243609",
  "photo_image_link": "https://img.sofascore.com/api/v1/player/243609/image",
  "average_sofascore_rating": 7.36
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@sofascore",
  "visibility": "public",
  "operation": "get_match",
  "version": 1,
  "input": {
    "team_1": "Barcelona",
    "team_2": "Real Madrid"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@sofascore\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_match\",\n  \"version\": 1,\n  \"input\": {\n    \"team_1\": \"Barcelona\",\n    \"team_2\": \"Real Madrid\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@sofascore",
  "visibility": "public",
  "operation": "get_match",
  "version": 1,
  "input": {
    "team_1": "Barcelona",
    "team_2": "Real Madrid"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/sofascore`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `get_match`: Get match. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `get_player_season_stats`: Get player season stats. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-sofascore https://api.fous.com/mcp/tools/sofascore --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Track scores and incidents for recent or dated football matches
- Compare player ratings and minutes played across a match
- Review player goals, assists, and appearances by season
- Analyze expected goals and goalkeeper saves for a competition
- Monitor cards and clean sheets across a player’s season

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this SofaScore tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a SofaScore account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from sofascore.com when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### What was the score between two football teams?

Get match returns the score for two named teams, using the most recent played or live match unless you provide a date.

### Who scored and assisted in a match?

Get match returns goal scorers, assists, teams, and minutes when that incident data is available.

### How many goals did a player score this season?

Get player season stats returns goals and other season statistics for a named player, with optional competition and season.

## Related

- [ESPN API](https://fous.com/tools/espn.md): ESPN provides daily scores and schedules, team results, player statistics, matchup summaries, and latest topic-specific headlines; coverage and published details vary, especially for college and soccer.
- [Flashscore API](https://fous.com/tools/flashscore.md): Live sports scores and match results.
- [Premier League API](https://fous.com/tools/premier-league.md): Premier League provides current/chosen-season tables and recent form, date-range fixtures/results (up to 380), player profiles and stats, and seasonal leaders; older-season stats may be limited.
- [Yahoo Sports API](https://fous.com/tools/yahoo-sports.md): Yahoo Sports returns date-based scores and schedules, seasonal standings, and player regular-season and career stats when Yahoo provides them; unavailable data may be missing.
- [NFL API](https://fous.com/tools/nfl.md): NFL provides weekly scores and schedules, regular-season standings, current rosters, and player season and career stats; released players are excluded, and ages or stats may be unavailable.
- [MLB API](https://fous.com/tools/mlb.md): MLB provides scores, schedules and game details for one date or up to seven days, regular-season division standings defaulting to the current year, and player profiles with regular-season stats for a selected season and career.
- [NHL API](https://fous.com/tools/nhl.md): NHL provides games, schedules, and scores when published, standings by date, and player profiles with regular-season stats; dates outside a season have no teams, and unavailable stats are null.
- [UEFA API](https://fous.com/tools/uefa.md): UEFA provides football competitions, matches and results, including club competition fixtures and scores by date range and current league-phase or group-stage tables.
- [All Sports tools](https://fous.com/tools/category/sports)