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

> Access comprehensive horse racing information including today's and tomorrow's fixtures, detailed runner data with jockey and trainer information, and Timeform's expert ratings to help inform your betting decisions. Get real-time insights on top-rated horses and make smarter racing selections with professional-grade data at your fingertips.

**Category:** Sports | **Website:** [www.timeform.com/horse-racing](https://www.timeform.com/horse-racing) | **Docs:** [parse.bot/marketplace/2ea033d4-2124-414c-aa8e-d04099664251/timeform-com-api](https://parse.bot/marketplace/2ea033d4-2124-414c-aa8e-d04099664251/timeform-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-timeform-com-api-2ea033d4/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_fixtures

Returns racing fixtures for today or tomorrow, listing all courses with their going conditions and individual races (time, name, number of runners, status). Courses are grouped by region (GB & Ire, USA, etc). Each race includes a status of 'result' (already run) or 'upcoming'. The number in parentheses in race names indicates declared runners; some divided races may show null for num_runners until final declarations.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `day` | string | No | Which day's fixtures to retrieve. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-timeform-com-api-2ea033d4/get_fixtures \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"day":"<string>"}'
```

### get_free_race_pass

Returns today's free daily race pass — Timeform's selection of a featured race with their top-rated horses including actual Timeform ratings, jockey/trainer, and performance flags (e.g. 'Horse In Focus', 'Horse For Course Positive Flag'). Typically shows the top 3 rated horses for one race. This is the only publicly accessible source of Timeform ratings on the site.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-timeform-com-api-2ea033d4/get_free_race_pass \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_todays_runners

Returns today's runners sorted alphabetically by horse name, filtered by starting letter. Each runner includes cloth number, horse name and code, jockey and trainer with their codes, and race context (course_id, race_number, meeting_date) when available from betting data. Some runners that have already raced may have null course_id/race_number. Horse/jockey/trainer codes are Timeform internal identifiers.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `letter` | string | No | Single uppercase letter A-Z to filter runners alphabetically. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-timeform-com-api-2ea033d4/get_todays_runners \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"letter":"<string>"}'
```