A "next up" strip
days=1 gives you today only, ordered by off time, which is the list you want above the fold.
Documentation / Racecards & meetings
Upcoming
GET
/v1/racecards/upcoming
Declarations for the next few days.
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 |
|---|---|---|---|---|
| days | query | integer | no | How many days from today, 1 to 7. Defaults to 2, meaning today and tomorrow. |
Request
curl https://api.apihorseracing.com/v1/racecards/upcoming \ -H "X-API-Key: $AHR_KEY"
$ch = curl_init('https://api.apihorseracing.com/v1/racecards/upcoming'); 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/upcoming', { 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/upcoming", headers={"X-API-Key": os.environ["AHR_KEY"]}, ).json()
curl https://api.apihorseracing.com/v1/racecards/upcoming?key=$AHR_KEY
$url = 'https://api.apihorseracing.com/v1/racecards/upcoming' . '?key=$AHR_KEY'; $data = json_decode(file_get_contents($url), true)['data'];
const res = await fetch( 'https://api.apihorseracing.com/v1/racecards/upcoming?key=$AHR_KEY' ); const { meta, data } = await res.json();
import os, requests r = requests.get( "https://api.apihorseracing.com/v1/racecards/upcoming?key=$AHR_KEY", ).json()
Response
200 OK
application/json
harvested 8 days ago
{ "meta": { "request_id": "0055188479d1aa00", "data_as_of": "2026-09-12T05:10:27+00:00", "plan": "analyst", "window": "2017 → upcoming", "from": "2026-09-13", "to": "2026-09-14", "count": 0 }, "data": [] }
A real response from /v1/racecards/upcoming,
captured by calling the live API rather than written by hand.
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. |
| 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
Declarations from today forward, as a flat list ordered by date and time rather than grouped, because a multi-day view is read chronologically rather than by track.
How far ahead anything exists depends on the jurisdiction. Britain declares 48 hours out for most races and five days for some; other countries publish later. Asking for seven days does not create races that have not been declared.
Common uses
Preparing overnight
Run once in the evening with days=2 and you have tomorrow ready before anyone asks for it.
Notes
Capped at 500 races. If you are hitting that, you want /v1/races/search with a date range and a cursor instead.