# Footystats — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://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.

> Get live football scores, team performance metrics, league standings, and head-to-head match statistics all in one place. Search teams and leagues to access detailed player stats, comprehensive analytics, and in-depth performance data across football competitions worldwide.

**Category:** Sports | **Website:** [footystats.org/](https://footystats.org/) | **Docs:** [parse.bot/marketplace/f86e936e-49e8-4880-b7a4-696d199e6da0/footystats-org-api](https://parse.bot/marketplace/f86e936e-49e8-4880-b7a4-696d199e6da0/footystats-org-api)

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

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/footystats/`
**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 detailed stats

Get league recent form table showing team performance over the last 6 matches. Returns form table entries with wins, draws, losses, goals, goal difference, points, and points per game. Also includes links to related stat pages when available.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | League path (e.g. '/england/premier-league'). Obtain from get_leagues results. |

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

### Get league overview

Get league overview including the full standings table. Returns league name, standings array (team rankings with match stats, goal difference, points, and points per game), and info metadata (nation, division, teams count).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | League path (e.g. '/england/premier-league'). Obtain from get_leagues results or search_teams_leagues results where category is 'league'. |

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

### Get league player stats

Get league player statistics: top scorers, assists leaders, and players with the most clean sheets. Each player entry includes name and stat value (goals/assists/clean sheets count as a string).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | League path (e.g. '/england/premier-league'). Obtain from get_leagues results. |

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

### Get leagues

List all football leagues available on FootyStats. Returns league metadata including name, country, slug, path, and full URL. The path field can be passed directly to get_league_overview, get_league_player_stats, or get_league_detailed_stats.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/footystats/get-leagues \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get livescores

Get today's football match scores across all leagues. Returns an array of matches with home/away team names, scores, and status. Status values include 'FT' (full time), 'HT' (half time), numeric minute values for in-progress matches, 'Stats' for upcoming scheduled matches, and 'Scheduled' when no indicator is present.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/footystats/get-livescores \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get match stats

Get match statistics for a specific head-to-head fixture. Returns match title, score, team names, and detailed stats (possession, shots, cards, corners, fouls, xG) for both teams. Stats keys vary by match but values always map team names to their stat values.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | Match path ending in -h2h-stats (e.g. '/england/arsenal-fc-vs-tottenham-hotspur-fc-h2h-stats'). Obtain from search_teams_leagues results where category is 'match'. |

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

### Get team stats

Get detailed team statistics for a single club. Returns win/draw/loss percentages, goals, possession, shots, fouls, and season totals — each broken down by overall, home, and away. The stats keys are open (vary by team/season) but each value carries overall/home/away splits.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | Team path starting with /clubs/ (e.g. '/clubs/arsenal-fc-59'). Obtain from search_teams_leagues results where category is 'club'. |

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

### Search teams leagues

Full-text search across teams, leagues, and matches by keyword. Returns mixed results categorized as 'club', 'league', or 'match', each carrying a path usable with the corresponding detail endpoint (get_team_stats, get_league_overview, get_match_stats). Results are not paginated — one request returns all matches.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword (e.g. 'arsenal', 'premier league', 'barcelona'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/footystats/search-teams-leagues \
  -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://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.