Head to head

GET /v1/horses/compare

Every race these horses have both run in, and who finished ahead.

Available on

Free key 24h – 7d

Live today + 3 days

Archive back to 2017

Complete 2017 → upcoming

Complete + Analyst 2017 → upcoming

Send your key in the X-API-Key header, or as ?key= if your tool cannot set one. A date outside your plan's window returns 403 outside_window naming the window, never an empty array.

Parameters

Name	In	Type	Required	Description
ids	query	string	yes	Two to five horse identifiers, comma separated.

Request

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

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

Response

200 OK application/json harvested 8 days ago

{
    "meta": {
        "request_id": "58fb1a44fdd03580",
        "data_as_of": "2026-09-12T05:10:27+00:00",
        "plan": "analyst",
        "window": "2017 → upcoming",
        "met": 0,
        "count": 0
    },
    "data": {
        "horses": [
            {
                "horse_id": "hs_V8JGH6",
                "name": "The Galloping Bear",
                "finished_ahead": 0
            },
            {
                "horse_id": "hs_V8JGH6",
                "name": "The Galloping Bear",
                "finished_ahead": 0
            }
        ],
        "meetings": []
    }
}

A real response from /v1/horses/compare?horses=hs_V8JGH6,hs_V8JGH6, 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
horse_id	string	Opaque horse identifier.
name	string	Race title as published, sponsor and all.

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.
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.

ids

What this is for

Every race these horses have both run in, and who finished ahead of whom. The question a form line cannot answer, because it requires joining two careers on the races they share.

Only races where both completed count towards the head-to-head record. A horse that pulled up has not been beaten by the winner in any meaningful sense, and counting it as a defeat would quietly reward the horses that stayed on their feet.

Common uses

Previewing a rematch

Two runners in today's race that have met before, with what happened each time.

Sanity-checking a rating

If your model has A above B and they have met four times with B winning three, one of you is wrong.

Notes

Horses that have never met return an empty meetings array rather than an error. Never having met is a real answer.