Documentation / Reference

What a free key reaches

The same production database every paid plan reads, on a delayed window. Not a sandbox, not sample data, and not a trial.

The window

A free key reads from seven days ago to twenty-four hours ago. Today's racing sits on the far side of that line, and so does anything older than a week. The window moves with the clock, so it never runs out.

# inside the window: three days ago
curl -H "X-API-Key: $KEY" \
  "https://api.apihorseracing.com/v1/results/2026-09-19"

# outside it: today
curl -H "X-API-Key: $KEY" \
  "https://api.apihorseracing.com/v1/results/2026-09-22"

The second returns an error rather than an empty list, because a blank result looks like missing data and this is not:

{
  "error": {
    "code": "outside_window",
    "message": "A free key reads 2026-09-07 to 2026-09-13. Requested 2026-09-14.",
    "your_window": { "from": "2026-09-07", "to": "2026-09-13" }
  }
}

What it reaches

37 of the 63 endpoints, inside that window:

Group	Reachable
Reference & coverage	7 of 7
Racecards & meetings	7 of 7
Races & markets	7 of 7
Horses & pedigree	5 of 8
Trainers	3 of 7
Jockeys & owners	5 of 10
Webhooks & account	3 of 3

What it does not reach

Two groups need a paid plan whatever the date, because they are not a question of window:

Race reports — 2 endpoints
Courses & bias — 6 endpoints
Market & analysis — 6 endpoints

These are the computed statistics and the written race reports. Everything else is available to you, just not at today's date.

Limits

Limit	Free key	On exceeding it
Requests a minute	60	`429` with `Retry-After`. Wait and carry on.
Requests a month	15,000	`429` with `quota_exceeded`. Retrying will not help until it resets.

Both figures come back on every response, so you never have to guess:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 34
X-Quota-Limit: 15000
X-Quota-Remaining: 14832

The usage endpoint returns the same figures if you would rather poll than read headers.

Checking your own window

One call answers what exists and what your key personally reaches, which makes it worth making at startup:

curl -H "X-API-Key: $KEY" "https://api.apihorseracing.com/v1/meta/coverage"

The meta block on every response carries your plan and window too, so the answer is never more than one request away.

Getting one

Get a free key — that page covers the three calls worth making first, and what each one tells you.