Form line

Parameters

Name	In	Type	Required	Description
horse_id	path	string	yes	Opaque horse identifier.
limit	query	integer	no	1 to 100. Defaults to 20.
cursor	query	string	no	Opaque. Pass next_cursor from the previous response.

Request

curl https://api.apihorseracing.com/v1/horses/hs_V8JGH6/form \
  -H "X-API-Key: $AHR_KEY"

$ch = curl_init('https://api.apihorseracing.com/v1/horses/hs_V8JGH6/form');
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/horses/hs_V8JGH6/form',
  { 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/horses/hs_V8JGH6/form",
    headers={"X-API-Key": os.environ["AHR_KEY"]},
).json()

Response

200 OK application/json harvested 8 days ago

{
    "meta": {
        "request_id": "1402f6a04b869352",
        "data_as_of": "2026-09-12T05:10:27+00:00",
        "plan": "analyst",
        "window": "2017 → upcoming",
        "horse_id": "hs_V8JGH6",
        "count": 3,
        "searched": {
            "from": null,
            "to": null
        }
    },
    "data": [
        {
            "race_id": "rc_KFH25J",
            "date": "2024-04-07",
            "course_id": "cr_3TBWR5E",
            "course": "Exeter",
            "run_type": null,
            "class": "3",
            "distance": "3m 6f 153y",
            "going": "Heavy (Soft in places)",
            "surface": "TURF",
            "runners": 6,
            "position": null,
            "casualty": "PulledUp",
            "beaten_distance": null,
            "sp": "10/3",
            "sp_decimal": 4.3333,
            "favourite": false,
            "market_position": 2,
            "weight": "12-0",
            "official_rating": 135,
            "headgear": "Cheek pieces, Tongue strap",
            "jockey_id": "jk_3V4QSXV",
            "jockey": "Joe Anderson",
            "trainer_id": "tr_2QVAXT3",
            "trainer": "Ben Clarke",
            "last_run_days": 7
        },
        {
            "race_id": "rc_3FNWHN5",
            "date": "2024-03-31",
            "course_id": "cr_3T63GQR",
            "course": "Ffos Las",
            "run_type": null,
            "class": "3",
            "distance": "3m 3f 208y",
            "going": "Heavy",
            "surface": "TURF",
            "runners": 7,
            "position": 2,
            "casualty": null,
            "beaten_distance": null,
            "sp": "11/1",
            "sp_decimal": 12,
            "favourite": false,
            "market_position": 5,
            "weight": "12-0",
            "official_rating": 135,
            "headgear": "Cheek pieces, Tongue strap",
            "jockey_id": "jk_BXRPGG",
            "jockey": "Sam Twiston-Davies",
            "trainer_id": "tr_2QVAXT3",
            "trainer": "Ben Clarke",
            "last_run_days": 36
        },
        "… 1 more"
    ]
}

A real response from /v1/horses/hs_V8JGH6/form?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
race_id	string	Opaque race identifier. Stable, and safe to store.
date	date	Race date, YYYY-MM-DD.
course_id	string	Opaque course identifier.
course	string	Course name.
run_type	string	Flat, Hurdle, Chase or NH Flat.
class	string	Race class.
distance	string	Official distance as published, e.g. "3m 3f 119y".
going	string	Ground description at the off.
surface	string	Turf, Dirt, Polytrack and so on.
runners	integer	Runners who took part.
position	integer	Finishing position. Null means the runner did not complete or was not published below the placings.
casualty	string	Why a runner did not complete: PulledUp, Fell, UnseatedRider, BroughtDown, RefusedToRace, RanOut.
beaten_distance	string	Distance behind the horse in front.
sp	string	Starting price, fractional, as returned.
sp_decimal	number	Starting price as a decimal, computed once at load so you are not parsing fractions per row.
favourite	boolean	Shortest price in the race. Joint favourites are all flagged.
market_position	integer	Rank by price, one being shortest. Ties share a rank.
weight	string	Weight carried, stones and pounds.
official_rating	integer	Handicap mark. Values outside 0 to 200 are dropped as source errors.
headgear	string	Blinkers, cheekpieces, tongue tie and so on.
jockey_id	string	Opaque jockey identifier.
jockey	string	Rider name.
trainer_id	string	Opaque trainer identifier.
trainer	string	Trainer name.
last_run_days	integer	Days since this horse last ran. Null on a first run.

What varies by jurisdiction

Run type is filled in behind the results crawl

The code a race was run under lives on the horse profile rather than the race, so it arrives on a later pass. A null run_type means not yet fetched, not unclassified.

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.

Not every jurisdiction publishes a full finishing order

America publishes the placings and nothing below them, so position is null for most of the field. Britain, Ireland, France and South Africa carry a position for the great majority of runners. /v1/countries returns the current figure for each.

Beaten distances arrive with the pedigree pass

They are published on the horse profile rather than the result page, so they fill in behind the main crawl.

Official ratings are not universal

Britain, Ireland and America carry a rating on roughly three quarters of runners. France and Germany carry one on about three percent. Values outside 0 to 200 are dropped, because the source returns sentinels there rather than ratings.

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.
outside_window	403	You asked for a date your plan cannot see. The body names the window and the date you asked for. Search endpoints clamp instead of refusing, and report what they actually searched in meta.
not_found	404	The identifier is well formed but nothing has it. Distinct from invalid_id, which means the identifier itself is wrong.
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.
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.
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.

horse_id

limit optional

cursor optional

What this is for

The form line: every run we hold, newest first, with the date, course, distance, going, class, the price it went off at and where it finished.

This is the endpoint most likely to surprise you on a narrow plan. The form is clipped to the window your plan reads, so a free key sees a week of a horse's career rather than nine years of it. meta says how many runs were withheld, so you can tell a short career from a clipped one.

Days since the previous run is computed here rather than left for you to subtract, because it is the field almost everybody wants and getting it wrong across a year boundary is a classic bug.

Common uses

Rendering a form line

One call, already ordered. The finishing position and the price are on every row.

Detecting a return from a break

days_since_previous over about ninety is a layoff. Whether that matters is what /v1/horses/{horse_id}/layoff answers.

Building features for a model

Walk the cursor for a full career. Every row carries the conditions, so you are not making a second call per race.

Available on