# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/timeform/`
**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 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/credits/timeform/get-fixtures \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/timeform/get-free-race-pass \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/timeform/get-todays-runners \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"letter":"<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.