Backfilling a season
Loop the dates you need at your plan's rate. Nine years is about three thousand five hundred requests, which fits inside a single month on any paid plan.
Documentation / Racecards & meetings
Card by date
GET
/v1/racecards/{date}
The full card for any date, grouped into meetings.
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 |
|---|---|---|---|---|
| date | path | string | yes | YYYY-MM-DD. Anything else returns invalid_param rather than being guessed at. |
Request
curl https://api.apihorseracing.com/v1/racecards/2021-02-28 \ -H "X-API-Key: $AHR_KEY"
$ch = curl_init('https://api.apihorseracing.com/v1/racecards/2021-02-28'); 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/racecards/2021-02-28', { 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/racecards/2021-02-28", headers={"X-API-Key": os.environ["AHR_KEY"]}, ).json()
curl https://api.apihorseracing.com/v1/racecards/2021-02-28?key=$AHR_KEY
$url = 'https://api.apihorseracing.com/v1/racecards/2021-02-28' . '?key=$AHR_KEY'; $data = json_decode(file_get_contents($url), true)['data'];
const res = await fetch( 'https://api.apihorseracing.com/v1/racecards/2021-02-28?key=$AHR_KEY' ); const { meta, data } = await res.json();
import os, requests r = requests.get( "https://api.apihorseracing.com/v1/racecards/2021-02-28?key=$AHR_KEY", ).json()
Response
200 OK
application/json
harvested 8 days ago
{ "meta": { "request_id": "ea62bc0c312c6369", "data_as_of": "2026-09-12T05:10:27+00:00", "plan": "analyst", "window": "2017 → upcoming", "date": "2021-02-28", "meetings": 17, "count": 131 }, "data": [ { "meeting_id": "mt_3W3QQ1S", "course_id": "cr_3GTJBD7", "course": "Aqueduct", "country": "USA", "region": "USA", "date": "2021-02-28", "going": "Sloppy", "surface": "DIRT", "races": [ { "race_id": "rc_14B8W8N", "meeting_id": "mt_3W3QQ1S", "course": "Aqueduct", "time": "18:20", "off_time": "18:22:30", "name": "Race 1 - Maiden Special Weight", "run_type": null, "class": null, "distance": "1m", "going": "Sloppy", "surface": "DIRT", "handicap": false, "runners": 6, "result_available": true }, { "race_id": "rc_3N8QXQ4", "meeting_id": "mt_3W3QQ1S", "course": "Aqueduct", "time": "18:51", "off_time": "18:51:43", "name": "Race 2 - Starter Allowance", "run_type": null, "class": null, "distance": "6f", "going": "Sloppy", "surface": "DIRT", "handicap": false, "runners": 6, "result_available": true }, "… 6 more" ] }, { "meeting_id": "mt_2TRYEEK", "course_id": "cr_2YQ4YV7", "course": "Bordeaux Le Bouscat", "country": "FR", "region": "FR", "date": "2021-02-28", "going": "Very Soft", "surface": "TURF", "races": [ { "race_id": "rc_345MEVD", "meeting_id": "mt_2TRYEEK", "course": "Bordeaux Le Bouscat", "time": "10:05", "off_time": "10:06:19", "name": "H. Bassie Chase", "run_type": null, "class": null, "distance": "2m 2f 195y", "going": "Very Soft", "surface": "TURF", "handicap": false, "runners": 6, "result_available": true }, { "race_id": "rc_1N13C9W", "meeting_id": "mt_2TRYEEK", "course": "Bordeaux Le Bouscat", "time": "10:35", "off_time": "10:38:38", "name": "Anglo-course Stakes", "run_type": null, "class": null, "distance": "1m 3f 204y", "going": "Very Soft", "surface": "TURF", "handicap": false, "runners": 9, "result_available": true }, "… 6 more" ] }, "… 15 more" ] }
A real response from /v1/racecards/2021-02-28,
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 |
|---|---|---|
| meeting_id | string | Opaque meeting identifier. A meeting is one course on one day. |
| course_id | string | Opaque course identifier. |
| course | string | Course name. |
| country | string | Country code as the source publishes it. |
| region | string | Jurisdiction, normalised. Welsh and Scottish racing is GB. |
| date | date | Race date, YYYY-MM-DD. |
| going | string | Ground description at the off. |
| surface | string | Turf, Dirt, Polytrack and so on. |
| race_id | string | Opaque race identifier. Stable, and safe to store. |
| time | string | Scheduled off time, local to the course. |
| off_time | string | Actual off time where recorded. |
| name | string | Race title as published, sponsor and all. |
| run_type | string | Flat, Hurdle, Chase or NH Flat. |
| class | string | Race class. |
| distance | string | Official distance as published, e.g. "3m 3f 119y". |
| handicap | boolean | Whether the race was run off official ratings. |
| runners | integer | Runners who took part. |
| result_available | boolean | Whether a result has been published. |
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.
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_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.
Remembered in this browser so you do not paste it on every page. Forget it
What this is for
The full card for any date in the archive, grouped into meetings exactly as today's card is. Past dates come back with results attached where they exist; future dates come back as declarations.
This is the endpoint to reach for when backfilling. Walking dates is cheaper than searching, because a day is a natural page: one request returns everything that ran, with no cursor to manage and no risk of a page shifting under you.
Common uses
Rebuilding one day after a correction
Results are corrected upstream occasionally. Re-fetching a date is idempotent and cheaper than diffing.
A date picker in your own product
One call per date the user chooses, no state to keep.
Notes
A date outside your plan's window returns outside_window naming both the window and the date you asked for. It never returns an empty card, because an empty card and a refused one mean very different things.