# Whoscored — 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.

> Search for players and teams, then dive deep into their performance metrics, match statistics, and detailed passing data to analyze football games and player abilities. Get comprehensive insights on team performance, individual player stats, and play-by-play event information to power your football analysis and decision-making.

**Category:** Sports | **Website:** [whoscored.com/](https://whoscored.com/) | **Docs:** [parse.bot/marketplace/16df779e-f6ee-4b02-a8c5-9f5efc49f125/whoscored-com-api](https://parse.bot/marketplace/16df779e-f6ee-4b02-a8c5-9f5efc49f125/whoscored-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/whoscored/`
**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 match events

Retrieve all match centre events for a specific completed match, including passes with origin (x, y) and destination (endX, endY) coordinates, player info, event type, outcome, and qualifiers. The match_id is obtainable from match links on tournament pages. Only completed matches with Opta data will return events; future or non-Opta matches return an upstream error. The response contains all events in a single request (typically 1000-2000 events per match). Page size is ~1.5MB due to embedded data.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `match_id` | string | Yes | Numeric match ID from WhoScored (found in match page URLs, e.g. 1729441 for Tottenham vs Man City) |

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

### Get player stats

Retrieve seasonal statistics for a specific player across all tournaments they have participated in. Returns per-season records including rating, goals, appearances, assists, pass success rate, shots per game, and more. The player_id is obtainable from the search endpoint.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_id` | string | Yes | Numeric player ID from WhoScored (obtainable from search endpoint results) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/whoscored/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 stats

Retrieve seasonal statistics for a specific team across all tournaments it participates in. Returns per-tournament records including rating, goals, possession percentage, pass success rate, shots per game, and cards. The team_id is obtainable from the search endpoint.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `team_id` | string | Yes | Numeric team ID from WhoScored (obtainable from search endpoint results) |

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

### List matches

Retrieve all fixtures and results for a specific team. For current active seasons, data comes from the team's fixtures page in a single request. When a season parameter is provided and matches for that season are archived (e.g. a completed league season), the endpoint fetches archived tournament data by iterating through monthly fixture feeds, resulting in ~14 requests total. Each match includes match_id (usable with get_match_events), date, kickoff time, home/away teams with IDs, score (null for upcoming), status, tournament name, and season. Results are chronologically ordered across all tournaments the team participates in.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `season` | string | No | Season to filter by in YYYY/YYYY format (e.g. '2024/2025'). When omitted, returns matches from all current seasons. |
| `team_id` | string | Yes | Numeric team ID from WhoScored (obtainable from search endpoint results) |

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

### Search

Full-text search over WhoScored's player and team database. Returns matching players (with IDs, slugs, current team, age) and teams (with IDs, slugs, country). A query that matches only players returns an empty teams array and vice versa. Results are unordered and unpaginated — the server returns all matches in a single response.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword (player or team name) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/whoscored/search \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"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.