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

> Get instant access to comprehensive sports statistics, player performance data, and team information across NBA, NFL, MLB, NHL, and more using natural language queries. Search for specific athletes or teams and discover historical sports information with intuitive search suggestions.

**Category:** Sports | **Website:** [statmuse.com/](https://statmuse.com/) | **Docs:** [parse.bot/marketplace/7bbfe23f-5a0a-4a90-9eb3-8af61b23e0d7/statmuse-com-api](https://parse.bot/marketplace/7bbfe23f-5a0a-4a90-9eb3-8af61b23e0d7/statmuse-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/statmuse/`
**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

### Ask

Submit a natural language sports question to StatMuse and receive a text answer with optional structured statistical tables. Supports questions about any sport covered by StatMuse (NBA, NFL, MLB, NHL, etc.). The query is interpreted server-side; ambiguous phrasing may yield unexpected results or empty tables. Each response includes a permalink URL.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Natural language sports query (e.g., 'Who has the most points in NBA history?', 'LeBron James stats last 10 games') |

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

### Get player stats

Get detailed player statistics by providing a player name and optional timeframe. Constructs a natural language query internally and returns the answer with game-by-game or aggregated statistical tables. The timeframe is flexible natural language (e.g., 'last 10 games', '2024-25 season', 'career').

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `player_name` | string | Yes | Full name of the player (e.g., 'LeBron James', 'Stephen Curry') |
| `timeframe` | string | No | Timeframe for stats (e.g., 'last 10 games', '2024-25 season', 'career') |

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

### Get team info

Get comprehensive team information including game logs, historical records, or roster data. Constructs a natural language query from the team name and query type. The query_type is flexible natural language describing what to retrieve.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query_type` | string | No | Type of information to retrieve (e.g., 'stats last 10 games', 'historical record', 'roster') |
| `team_name` | string | Yes | Team name (e.g., 'Lakers', 'Golden State Warriors', 'Patriots') |

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

### Search suggestions

Get search suggestions for a partial query. Returns categorized suggestion sections including player names, team names, and related queries. Useful for autocomplete or discovering valid player/team identifiers before querying stats.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Partial query to get suggestions for (e.g., 'LeBron', 'Warriors', 'touchdown') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/statmuse/search-suggestions \
  -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.