# Fbref — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access comprehensive football statistics including player profiles, team performance data, league standings, and detailed match reports all in one place. Search for specific players and teams, compare their stats, and get up-to-date information on leagues and match outcomes.

**Category:** Sports | **Website:** [fbref.com/](https://fbref.com/) | **Docs:** [parse.bot/marketplace/b8a46b5c-6a19-4d2a-96aa-68af1eefdd0e/fbref-com-api](https://parse.bot/marketplace/b8a46b5c-6a19-4d2a-96aa-68af1eefdd0e/fbref-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/fbref/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get league player stats

Get league-wide player statistics leaderboard for a competition and season. Returns all players who appeared in the league with player_id, name, team, position, age, minutes, and stat-type-specific metrics. The stat_type parameter selects which stat category: stats (standard: games, goals, assists, per-90), passing (passes completed/attempted, progressive passes, key passes, xA), passing_types (live/dead, through balls, crosses, corners), gca (shot-creating and goal-creating actions), defense (tackles, blocks, interceptions, clearances), or possession (touches, carries, take-ons, progressive carries). Useful for discovery and cross-player comparison.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `comp_id` | string | Yes | FBref competition ID (e.g. 9 for Premier League, 12 for La Liga, 20 for Bundesliga). |
| `season` | string | No | Season identifier (e.g. 2024-2025). Strongly recommended; omitting attempts to detect the current season which may fail for some competitions. |
| `stat_type` | string | No | Stat category for the leaderboard. Each type returns different columns per player. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fbref/get-league-player-stats \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"comp_id":"<string>","season":"<string>","stat_type":"<string>"}'
```

### Get league standings

Get league standings/table for a specific competition and optional season. Returns full table with rankings, records, points, goal difference, and top scorers. Works for any FBref competition ID. Common IDs: 9 Premier League, 12 La Liga, 20 Bundesliga, 11 Serie A, 13 Ligue 1, 22 Major League Soccer, 73 USL Championship, 24 Brasileirão Série A, 38 Brasileirão Série B, 31 Liga MX, 32 Primeira Liga, 23 Eredivisie, 21 Argentine Primera División, 10 EFL Championship. MLS, Brazilian, and Liga MX seasons use single-year format (e.g. "2026") while European leagues use "YYYY-YYYY".

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `comp_id` | string | Yes | FBref competition ID. Common values: 9 (Premier League), 12 (La Liga), 20 (Bundesliga), 11 (Serie A), 13 (Ligue 1), 22 (MLS), 73 (USL Championship), 24 (Brasileirão Série A), 38 (Brasileirão Série B), 31 (Liga MX), 32 (Primeira Liga), 23 (Eredivisie), 21 (Argentine Primera División), 10 (EFL Championship). Accepts any valid FBref competition ID. |
| `season` | string | No | Season identifier. European leagues use YYYY-YYYY (e.g., 2024-2025). MLS, Brazilian, Argentine, and Liga MX seasons use single-year format (e.g., 2025). Omitting returns the current season. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fbref/get-league-standings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"comp_id":"<string>","season":"<string>"}'
```

### Get match report

Get match report including final score, teams, date, venue, and competition for a specific match.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `match_id` | string | Yes | FBref match ID (8-character hex identifier, e.g., 0b316a86). Obtainable from league schedules or team match pages. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fbref/get-match-report \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"match_id":"<string>"}'
```

### Get player advanced stats

Get player career advanced stats across all competitions broken down by season. Returns nine stat categories: standard (games, minutes, goals, assists, per-90), shooting (shots, shots_on_target, goals_per_shot), playing_time (minutes_per_game, games_complete, subs, plus_minus), miscellaneous (cards, fouls, offsides, interceptions, tackles_won), passing, pass_types, defense, possession, and gca. The first four are always populated from FBref career tables. The remaining five return empty arrays because FBref does not currently publish career-level tables for these on player pages; use get_league_player_stats or get_player_match_logs with the corresponding stat_type to access this data per-season or per-game.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_id` | string | Yes | FBref player ID (8-character hex identifier). Obtainable from search or get_team_stats results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fbref/get-player-advanced-stats \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"<string>"}'
```

### Get player match logs

Get game-by-game match logs for a player in a given season. Returns one row per match with date, opponent, competition, venue, game_started, position, minutes, and stat-type-specific columns. The stat_type parameter selects which stat category to retrieve: summary (goals, assists, shots, cards), passing (passes completed/attempted, pass completion %, progressive passes, key passes), passing_types (live/dead balls, through balls, crosses, corners), gca (shot-creating and goal-creating actions breakdown), defense (tackles, blocks, interceptions, clearances), or possession (touches, carries, take-ons, progressive carries). Each stat type fetches a separate FBref page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `comp_id` | string | No | Optional FBref competition ID to filter match logs to a specific competition (e.g. 9 for Premier League). Omitting returns all competitions. |
| `player_id` | string | Yes | FBref player ID (8-character hex identifier). Obtainable from search or get_team_stats results. |
| `season` | string | Yes | Season identifier in YYYY-YYYY format for European leagues (e.g. 2024-2025) or YYYY for single-year leagues. |
| `stat_type` | string | No | Stat category for the match logs. Each type returns different columns per match. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fbref/get-player-match-logs \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"comp_id":"<string>","player_id":"<string>","season":"<string>","stat_type":"<string>"}'
```

### Get player scouting report

Get player scouting stats for the most recent domestic league season across standard, shooting, playing time, and miscellaneous categories. Returns per-90 metrics, shooting efficiency, playing time details, and defensive/disciplinary stats from the player's scout page. Each category contains the most recent season's data. The code also looks for passing, pass_types, defense, possession, and gca tables; these are included when FBref publishes them but are currently absent from most player scout pages. Use get_league_player_stats or get_player_match_logs with the corresponding stat_type for per-season or per-game access to those categories.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_id` | string | Yes | FBref player ID (8-character hex identifier). Obtainable from search or get_team_stats results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fbref/get-player-scouting-report \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"<string>"}'
```

### Get player stats

Get player profile info and career-long standard statistics broken down by season and competition. Profile includes name, position, born, and current_club. Each season row includes games, games_starts, minutes, minutes_90s, goals, assists, and per-90 metrics (goals_per90, assists_per90, goals_assists_per90).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_id` | string | Yes | FBref player ID (8-character hex identifier, e.g., d70ce98e for Lionel Messi, 1f44ac21 for Erling Haaland). Obtainable from search or get_team_stats results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fbref/get-player-stats \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"<string>"}'
```

### Get team schedule

Get a team's fixtures and results across all competitions for a season. Returns one row per match with date, competition, venue, opponent, result, goals_for, goals_against, formation, and match_id for joining to get_match_report.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `season` | string | No | Season identifier (e.g. 2025-2026). Omitting returns the current season. |
| `team_id` | string | Yes | FBref team ID (8-character hex identifier, e.g. 18bb7c10 for Arsenal). Obtainable from search or get_league_standings results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fbref/get-team-schedule \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"season":"<string>","team_id":"<string>"}'
```

### Get team stats

Get team overview, manager, record, and squad player statistics for a season. Returns detailed per-player stats including games, goals, assists, and per-90 metrics.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `season` | string | No | Season in format YYYY-YYYY (e.g., 2025-2026). Omitting returns the current season. |
| `team_id` | string | Yes | FBref team ID (8-character hex identifier, e.g., 18bb7c10 for Arsenal, b8fd03ef for Manchester City). Obtainable from search or get_league_standings results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fbref/get-team-stats \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"season":"<string>","team_id":"<string>"}'
```

### Search

Search for players or squads by name. Returns matches with their IDs and profile URLs. If an exact match is found, FBRef redirects directly to the entity page and a single result with exact=true is returned.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `entity_type` | string | No | Type of entity to search for. Accepted values: players, squads. |
| `query` | string | Yes | Search query (player or team name) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fbref/search \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"entity_type":"<string>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.