Precedents

Parameters

Name	In	Type	Required	Description
race_id	query	string	no	Take the conditions from this race. Simpler than describing them by hand.
course_id	query	string	no	One course.
distance	query	string	no	One distance.
going	query	string	no	One going.
run_type	query	string	no	One run type.
class	query	string	no	One class.
field_size	query	string	no	A field size band.
limit	query	integer	no	1 to 200. Defaults to 50.

Request

curl https://api.apihorseracing.com/v1/analysis/precedents \
  -H "X-API-Key: $AHR_KEY"

$ch = curl_init('https://api.apihorseracing.com/v1/analysis/precedents');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: ' . getenv('AHR_KEY')],
]);
$data = json_decode(curl_exec($ch), true)['data'];

const res = await fetch(
  'https://api.apihorseracing.com/v1/analysis/precedents',
  { headers: { 'X-API-Key': process.env.AHR_KEY } }
);
const { meta, data } = await res.json();

import os, requests

r = requests.get(
    "https://api.apihorseracing.com/v1/analysis/precedents",
    headers={"X-API-Key": os.environ["AHR_KEY"]},
).json()

Response

200 OK application/json harvested 8 days ago

{
    "meta": {
        "request_id": "2d2605f745a94ab1",
        "data_as_of": "2026-09-12T05:10:27+00:00",
        "plan": "analyst",
        "window": "2017 → upcoming",
        "count": 3
    },
    "data": {
        "matched_on": {
            "course_id": "cr_JSRC8Z",
            "distance": "3m 1f 210y",
            "going": "Soft (Good to Soft in places)"
        },
        "window": {
            "from": null,
            "to": null,
            "note": "The whole archive. Your plan sets no date limit."
        },
        "aggregate": {
            "runs": 27,
            "priced": 27,
            "first": 5,
            "second": 5,
            "third": 5,
            "fourth": 1,
            "win_pct": 0.1852,
            "top3_pct": 0.5556,
            "expected_wins": 5,
            "a_e": 1,
            "a_e_range": [
                0.123,
                1.877
            ],
            "a_e_beats_market": false,
            "significant": false,
            "low_sample": true,
            "pl_1pt": -8.18,
            "roi_pct": -30.28
        },
        "races": [
            {
                "race_id": "rc_EA7W9N",
                "date": "2022-12-26",
                "course": "Fontwell",
                "name": "Southern Cranes And Access Handicap Chase",
                "class": "4",
                "distance": "3m 1f 210y",
                "going": "Soft (Good to Soft in places)",
                "runners": 9,
                "winning_time": "7m 23.46s",
                "book_percentage": 119.37
            },
            {
                "race_id": "rc_3BCC5YR",
                "date": "2022-02-27",
                "course": "Fontwell",
                "name": "Manor Elite Horse Box Open Hunters' Chase",
                "class": "6",
                "distance": "3m 1f 210y",
                "going": "Soft (Good to Soft in places)",
                "runners": 4,
                "winning_time": "7m 18.20s",
                "book_percentage": 107.48
            },
            "… 1 more"
        ]
    }
}

A real response from /v1/analysis/precedents?race_id=rc_1P005G7&limit=3, captured by calling the live API rather than written by hand.

Response fields

Each field is described once and rendered on every endpoint that returns it, so the wording cannot drift between pages.

Field	Type	What it is
course_id	string	Opaque course identifier.
distance	string	Official distance as published, e.g. "3m 3f 119y".
going	string	Ground description at the off.
window	string	How far back and forward that plan can read.
runs	integer	Rides in the slice, priced or not.
priced	integer	Rides carrying a starting price. A/E and the profit figures use these; runs is the wider count.
first	integer	Wins.
second	integer	Seconds. Positions are returned separately so you apply your own place terms.
third	integer	Thirds.
fourth	integer	Fourths.
win_pct	number	Wins over runs. The number everyone quotes and the one that tells you least.
top3_pct	number	First, second or third over runs. Not a place strike rate; place terms vary.
expected_wins	number	Wins the market implied, summed over the slice.
a_e	number	Actual wins over expected. Above 1.00 means winning more often than the prices said.
a_e_range	array	Ninety five percent interval on A/E. If it spans 1.00 the figure is not evidence of anything.
a_e_beats_market	boolean	True only where the whole interval sits above 1.00.
significant	boolean	Whether the interval excludes 1.00 in either direction.
low_sample	boolean	Fewer than five expected wins. Treat A/E as noise.
pl_1pt	number	One point on every runner, settled at starting price.
roi_pct	number	Level stakes return. Backing everything loses more than the book margin, because equal stakes overweight the longshots.
race_id	string	Opaque race identifier. Stable, and safe to store.
date	date	Race date, YYYY-MM-DD.
course	string	Course name.
name	string	Race title as published, sponsor and all.
class	string	Race class.
runners	integer	Runners who took part.
winning_time	string	Winning time as published.
book_percentage	number	The field's implied probabilities added up. 100 would be a fair book; the excess is the margin. Ours average 117 in small fields and 133 in sixteen or more.

What varies by jurisdiction

Race class is a British idea

Class is published in Britain and reliably absent elsewhere. Do not treat a null class as an ungraded race.

Winning times are patchy outside Britain and Ireland

Where a time exists it is as published. /v1/courses/{id}/standard-times reports the median per distance and counts the implausible ones rather than quietly serving them.

Errors this endpoint returns

Code	Status	When
unauthorized	401	No key, or one we do not recognise. Check the header name and that the key has not been rotated from your account page.
upgrade_required	403	The endpoint returns computed statistics and your plan does not include them. The body names every plan that does reach it, so you never have to look it up.
invalid_param	422	A date that is not YYYY-MM-DD, a by= dimension we do not have, or a cursor that did not come from us. The message names the parameter.
invalid_id	422	The prefix does not match the kind of thing the path expects, or the identifier is malformed. A horse id passed where a race is wanted lands here rather than returning the wrong race.
rate_limited	429	Past your per-minute rate. Retry-After is set, and X-RateLimit-Remaining tells you where you stand on every successful response too.
server_error	500	Ours, not yours. Every response carries a request_id; quote it and we can find the exact request.

Run it live

A real request from your browser straight to api.apihorseracing.com with your own key. Nothing is proxied and nothing is logged by this page.

Your API key

Remembered in this browser so you do not paste it on every page.

race_id optional

course_id optional

distance optional

going optional

run_type optional

class optional

field_size optional

limit optional

What this is for

Races from the archive that ran under matching conditions, with what they produced: the winning prices, the favourite record, the field sizes and the times.

Pass a race_id and it takes the conditions from that race, which is far easier than describing them yourself and removes the risk of describing them slightly wrong.

The question it answers is the one a form book cannot: what usually happens in races like this one. Not what will happen, and not who will win, but the distribution of outcomes this shape of race has produced before.

Common uses

Previewing a race properly

Pass the race_id. The winning price distribution tells you whether this is a race favourites win or one that throws up prices.

Setting a realistic expectation

If forty comparable races produced eleven winning favourites, that is your starting point, not your model's confidence.

Finding a population to study

The race identifiers returned are a ready-made set to run through the other endpoints.

Notes

Matching is on conditions, not on quality. Two races at the same course, distance and going can be very different contests, and this will treat them as comparable.

Available on