---
name: horseracingapi
description: Official horse racing results from the USA, Great Britain, Ireland, France and South Africa since 2022 with HorseRacingAPI. Use when a question needs a race result, a finishing order, or a horse, jockey, trainer or owner's recent runs or record.
---

# HorseRacingAPI

HorseRacingAPI serves the official results of every race in five nations (USA, GB, IRE with Northern Ireland, FR, RSA) since 1 January 2022, live as they are declared. Each race has its conditions and every runner in finishing order with horse, jockey, trainer and owner.

## When to use it

Use it for who won, where a horse finished, a day's results, a horse's last ten runs, or a jockey, trainer or owner's record since 2022.

Not for odds or prices, sire, dam or breeding, prize money, ratings, racecards or declarations, predictions or tips, anything before 2022, or nations other than the five. None of these are in the data.

## Getting access

- A free key: sign in with Google at https://horseracingapi.org/free-key. It reads yesterday's results, nations, courses and usage: 50 calls a day.
- The Results plan, $29 a month or $299 a year, reads everything since 2022: https://horseracingapi.org/pricing
- Send the key in a header: `X-API-Key: hra_live_…` or `Authorization: Bearer hra_live_…`. Never in the address (that is a 400).
- Ask the user for their key; never invent one.

## The calls

Base: https://api.horseracingapi.org. Every call is GET and answers `{"data": …, "meta": {…}}`.

- Yesterday's results, every nation (free key): `GET /v1/results/yesterday?country=GB`
- A day of results since 2022: `GET /v1/results/2024-06-01?country=IRE`
- The newest results as they are declared: `GET /v1/results/latest`
- One race in full: `GET /v1/races/{race_id}`
- Races by date, nation, course or going: `GET /v1/races/search?date_from=2024-06-01&date_to=2024-06-07&country=GB`
- Find a horse, then its last ten runs: `GET /v1/horses/search?q=desert then /v1/horses/{horse_id}/form`
- A jockey and their last ten rides: `GET /v1/jockeys/search?q=moore then /v1/jockeys/{jockey_id}/rides`
- A trainer or owner record since 2022: `GET /v1/trainers/{trainer_id}, /v1/owners/{owner_id}`
- Nations and courses (free key): `GET /v1/countries, /v1/courses?country=FR`
- Your calls and limits, never counted: `GET /v1/usage`

```bash
curl "https://api.horseracingapi.org/v1/results/yesterday?country=GB" -H "X-API-Key: hra_live_…"
```

```json
{
  "data": [{
    "meeting_id": "mt_…", "course": "Newmarket", "country": "GB", "date": "…", "going": "Good",
    "races": [{
      "race_id": "rc_…", "time": "14:05", "name": "…", "distance": "1m", "runners": 9, "winning_time": "1:38.21",
      "finishing_order": [{"position": 1, "status": "finished", "horse_id": "hs_…", "horse": "…", "jockey_id": "jk_…", "jockey": "…", "trainer_id": "tr_…", "trainer": "…", "owner_id": "ow_…", "owner": "…"}]
    }]
  }],
  "meta": {"plan": "free", "data_as_of": "…", "count": 1, "page": 1, "total_pages": 4, "next_page": 2}
}
```

Ids carry their type (`rc_` race, `mt_` meeting, `cr_` course, `hs_` horse, `jk_` jockey, `tr_` trainer, `ow_` owner) and open with the matching endpoint.

## MCP server

https://horseracingapi.org/mcp, with the tools `latest_results`, `yesterdays_results`, `results_on_date`, `search_races`, `get_race`, `get_meeting`, `find_horse`, `get_horse`, `horse_form`, `find_jockey`, `get_jockey`, `jockey_rides`, `get_trainer`, `get_owner`, `list_courses`, `my_usage`. Each takes its endpoint's parameters. Tools: https://horseracingapi.org/documentation/mcp-tools

## Limits

- Free key: 10 calls a minute, 50 a day, yesterday's results only.
- Results plan: 60 a minute, 30,000 a month, everything since 2022-01-01.
- Form and rides: the last 10 runs only. No bulk downloads.
- Lists page with `page` and `per_page`; searches with `cursor` (pass `meta.next_cursor` back as it came).
- Headers: `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-Quota-Remaining`. Times are UTC; race times are the course's own.

## Errors

`{"error": {"code": "…", "message": "…", "docs": "https://horseracingapi.org/documentation/errors"}}`

- 400 `bad_request`: a value is the wrong shape. 401 `unauthorized`: no key or an unknown one.
- 403 `upgrade_required`: the free key does not open this endpoint; `plan` names the one that does.
- 404 `not_found`: no such id, or a date before 2022. 422 `unknown_parameter`: the answer lists the allowed ones.
- 429 `rate_limited` (wait `Retry-After` seconds) or `quota_exceeded`. 503 `server_error`: try again in a minute.

## A typical workflow

1. Ask the user for their key, or send them to https://horseracingapi.org/free-key.
2. Find the race: `/v1/results/{date}` for a known day, or `/v1/races/search` by course, nation and dates.
3. Open it with `/v1/races/{race_id}` for the full finishing order.
4. Follow a runner's `horse_id`, `jockey_id`, `trainer_id` or `owner_id` to its record or last ten runs.
5. On a 403, tell the user which plan opens it rather than retrying. On a 429, wait and retry once.
6. Say when a class or winning time is null: that nation does not publish it.

Full manual: https://horseracingapi.org/documentation/manual.md