# Ergast — 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 Formula 1 historical data dating back to 1950, including race results, driver and constructor standings, qualifying times, lap records, and pit stop information. Track driver and constructor performance across seasons, explore circuit details, and analyze standings to dive deep into F1 history.

**Category:** Sports | **Website:** [ergast.com/](https://ergast.com/) | **Docs:** [parse.bot/marketplace/8b44fd6c-7d55-4fc6-83b4-4973dd583dc7/ergast-com-api](https://parse.bot/marketplace/8b44fd6c-7d55-4fc6-83b4-4973dd583dc7/ergast-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/ergast/`
**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 circuit info

Get info for a specific circuit by their ID. Returns circuit name, location with latitude, longitude, locality, and country.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `circuit_id` | string | No | Circuit identifier (e.g. 'monza', 'silverstone', 'spa'). |

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

### Get circuits

Get a list of F1 circuits, optionally filtered by season.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return. |
| `offset` | integer | No | Result offset for pagination. |
| `season` | string | No | Filter by season year (e.g. '2023'). Omitting returns all circuits across all seasons. |

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

### Get constructor info

Get info for a specific constructor by their ID. Returns name and nationality.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `constructor_id` | string | No | Constructor identifier (e.g. 'mercedes', 'red_bull', 'ferrari'). |

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

### Get constructor season results

Get all race results for a specific constructor in a season. Returns every race the constructor participated in with results for both drivers.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `constructor_id` | string | No | Constructor identifier (e.g. 'mercedes', 'red_bull'). |
| `season` | string | No | Season year (e.g. '2023'). |

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

### Get constructor standings

Get the Constructor Championship standings after a specific round or at the end of a season.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `round` | string | No | Round number for standings after that round. Omitting returns end-of-season standings. |
| `season` | string | No | Season year (e.g. '2023') or 'current' for the current season. |

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

### Get constructors

Get a list of F1 constructors (teams), optionally filtered by season.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return. |
| `offset` | integer | No | Result offset for pagination. |
| `season` | string | No | Filter by season year (e.g. '2023'). Omitting returns all constructors across all seasons. |

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

### Get driver info

Get biographical info for a specific driver by their ID. Returns permanent number, code, full name, date of birth, and nationality.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `driver_id` | string | No | Driver identifier (e.g. 'hamilton', 'max_verstappen', 'leclerc'). |

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

### Get driver season results

Get all race results for a specific driver in a season. Returns every race the driver participated in with their finishing position and points.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `driver_id` | string | No | Driver identifier (e.g. 'hamilton', 'max_verstappen'). |
| `season` | string | No | Season year (e.g. '2023'). |

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

### Get driver standings

Get the Driver Championship standings after a specific round or at the end of a season.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `round` | string | No | Round number for standings after that round. Omitting returns end-of-season standings. |
| `season` | string | No | Season year (e.g. '2023') or 'current' for the current season. |

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

### Get drivers

Get a list of F1 drivers, optionally filtered by season. Returns driver biographical information including name, date of birth, and nationality.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return. |
| `offset` | integer | No | Result offset for pagination. |
| `season` | string | No | Filter by season year (e.g. '2023'). Omitting returns all drivers across all seasons. |

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

### Get finishing status

Get a list of all finishing status codes and their counts, optionally filtered by season and round.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `round` | string | No | Filter by round number (e.g. '1'). Requires season to be set. |
| `season` | string | No | Filter by season year (e.g. '2023'). |

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

### Get lap times

Get lap time data for every driver on a specific lap of a race.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lap_number` | string | No | Lap number to get times for. |
| `round` | string | No | Round number (e.g. '1') or 'last' for the most recent race. |
| `season` | string | No | Season year (e.g. '2023') or 'current' for the current season. |

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

### Get pit stops

Get pit stop data for a specific race including stop times and durations.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `round` | string | No | Round number (e.g. '1') or 'last' for the most recent race. |
| `season` | string | No | Season year (e.g. '2023') or 'current' for the current season. |
| `stop_number` | string | No | Filter by specific pit stop number (e.g. '1' for first stops only). |

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

### Get qualifying results

Get qualifying session results (Q1, Q2, Q3 times) for a specific race.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `round` | string | No | Round number (e.g. '1') or 'last' for the most recent race. |
| `season` | string | No | Season year (e.g. '2023') or 'current' for the current season. |

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

### Get race results

Get race results for a specific season and round. Returns finishing positions, points, lap times, and fastest laps for all drivers.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `round` | string | No | Round number (e.g. '1') or 'last' for the most recent race. |
| `season` | string | No | Season year (e.g. '2023') or 'current' for the current season. |

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

### Get race schedule

Get the full race schedule for a given season. Returns race dates, circuits, and session times (practice, qualifying). Can retrieve a single round's schedule when round is specified.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `round` | string | No | Specific round number to retrieve a single race's schedule. |
| `season` | string | No | Season year (e.g. '2023') or 'current' for the current season. |

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

### Get seasons

Get a list of all F1 seasons supported by the API. Returns season years with Wikipedia links. Supports pagination via limit and offset.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of results to return. |
| `offset` | integer | No | Result offset for pagination. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/ergast/get-seasons \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","offset":"<integer>"}'
```

### Get seasons for constructor

Get all seasons in which a specific constructor participated.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `constructor_id` | string | No | Constructor identifier (e.g. 'mercedes', 'red_bull'). |

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

### Get seasons for driver

Get all seasons in which a specific driver participated.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `driver_id` | string | No | Driver identifier (e.g. 'hamilton', 'max_verstappen'). |

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