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

> Search and analyze cross country and track & field performance data across the US, including athlete profiles, meet results, team rosters, and rankings. Access comprehensive meet information, historical records, and state-level competition data to track athlete progress and discover top performers.

**Category:** Sports | **Website:** [athletic.net/](https://athletic.net/) | **Docs:** [parse.bot/marketplace/cbf59ca1-164e-4ce3-a857-15597e030a58/athletic-net-api](https://parse.bot/marketplace/cbf59ca1-164e-4ce3-a857-15597e030a58/athletic-net-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/athletic/`
**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 athlete profile

Retrieve an athlete's full profile including biographical info, race history across seasons, team affiliations, and meet participation. Results include XC race times with distances and placements. The response merges athlete identity fields (IDAthlete, FirstName, LastName, Gender) at top level with meets, resultsXC, and allTeams.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `athlete_id` | string | Yes | Unique numeric ID of the athlete (AthleteID from search or meet results). |
| `sport` | string | No | Sport type: 'xc' for cross country, 'tf' for track & field. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/athletic/get-athlete-profile \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"athlete_id":"<string>","sport":"<string>"}'
```

### Get country meets

Retrieve all meets indexed for a specific country across all available years. Accepts ISO Alpha3 country codes (e.g. 'NZL', 'AUS', 'GBR'). Results are paginated with 12 meets per page, ordered chronologically. The sport parameter filters by cross country or track & field.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `country` | string | Yes | ISO Alpha3 country code (e.g. 'NZL' for New Zealand, 'AUS' for Australia, 'GBR' for United Kingdom). |
| `page` | integer | No | Page number for pagination (12 meets per page). |
| `sport` | string | No | Sport type: 'xc' for cross country, 'tf' for track & field. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/athletic/get-country-meets \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"country":"<string>","page":"<integer>","sport":"<string>"}'
```

### Get meet info

Retrieve metadata for a cross country or track & field meet including location, divisions, course details, and a JWT token needed for fetching meet results via get_meet_results. The sport parameter selects the database (xc or tf) — it does not filter meets.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `meet_id` | string | Yes | Unique numeric ID of the meet. |
| `sport` | string | No | Sport type: 'xc' for cross country, 'tf' for track & field. |

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

### Get meet results

Retrieve individual athlete results for a specific division/race within a meet. Internally fetches a JWT from get_meet_info before requesting results. Returns individual placements, team scores, and participating teams. The div_id comes from get_meet_info's xcDivisions[*].IDMeetDiv.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `div_id` | string | Yes | Division ID (IDMeetDiv) from get_meet_info's xcDivisions[*].IDMeetDiv or tfDivisions[*].IDMeetDiv. |
| `meet_id` | string | Yes | Unique numeric ID of the meet. |
| `sport` | string | No | Sport type: 'xc' for cross country, 'tf' for track & field. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/athletic/get-meet-results \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"div_id":"<string>","meet_id":"<string>","sport":"<string>"}'
```

### Get states

Retrieve the complete list of US states, Canadian provinces, and world countries supported by the site. Useful for building state/country filters.

**Estimated cost:** Metered

_No parameters required._

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

### Get team roster

Retrieve the list of athletes on a team's cross country roster for a given season year. Internally fetches a team JWT before requesting the athlete list. Returns athlete names, genders, and IDs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `team_id` | string | Yes | Unique numeric ID of the team/school (IDSchool from meet results or search). |
| `year` | string | No | Season year. |

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

### Get top rankings

Retrieve top cross country rankings for a specific division and gender. Returns ranked athletes with their best results, team names, and meet info. The div_id is a division ID (e.g. from search results or known state divisions like 74938 for Ohio HS).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `div_id` | string | Yes | Division ID for rankings lookup. |
| `gender` | string | No | Gender filter: 'm' for male, 'f' for female. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/athletic/get-top-rankings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"div_id":"<string>","gender":"<string>"}'
```

### Search

Full-text search across athletes, teams, and meets by keyword. Returns matching results with type classification (Team, XCMeet, TFMeet, Athlete) and relevance scores. Results are ordered by score descending. No pagination — returns up to ~10 best matches.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword, supports single and multi-word queries. |

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