GET

/v1/form

Race Form

Returns full race form data including runner details, career statistics, and form history for a specific race.

Find races before you fetch them

Not sure a race exists for your date and track? Call the meetings endpoint first — it lists every track slug and raceNumber running on a date. Passing those exact values here is the surest way to avoid 404 Not Found responses.

Parameters

datestring

required

Race date in YYYY-MM-DD format. Range: 30 days in the past to 7 days in the future.

trackstring

required

Track slug identifier (e.g. flemington, randwick). Use the Meetings endpoint to see which tracks are running on a given date, or the Venues endpoint to discover valid slugs.

raceinteger

required

Race number, from 1 to 20.

race_codestring

optional

Default: gallops

Race type: gallops, harness, or greyhounds.

countrystring

optional

Default: au

Two-letter country code. 24 countries supported including au, nz, hk, gb, us, jp, sg, fr, ie, and more.

timezonestring

optional

Default: Australia/Sydney

IANA timezone for date interpretation (e.g. Europe/London, America/New_York). The date you provide is interpreted in this timezone, so international users see meetings matching their local calendar date. Defaults to Australian Eastern time. This scopes which races you get — it does not shift the times in the response. startTime is always UTC regardless of what you pass here; use the timezone response field to render a local post time.

Code Examples

javascript

const response = await fetch(
  'https://api.formfav.com/v1/form?' +
  new URLSearchParams({
    date: '2026-01-15',
    track: 'flemington',
    race: '7',
    race_code: 'gallops',
    country: 'au'
  }),
  {
    headers: { 'X-API-Key': 'your_api_key_here' }
  }
);

const data = await response.json();

// International example — UK meeting from a London user's perspective
const ukResponse = await fetch(
  'https://api.formfav.com/v1/form?' +
  new URLSearchParams({
    date: '2026-03-19',
    track: 'newcastle',
    race: '1',
    race_code: 'gallops',
    country: 'gb',
    timezone: 'Europe/London'
  }),
  {
    headers: { 'X-API-Key': 'your_api_key_here' }
  }
);

Response Fields

Empty fields are omitted, not null

Any field marked omitted below is left out of the JSON entirely when it has no value — it is never returned as null. Check for presence ('claim' in runner), not for null, and type these as optional properties rather than nullable ones.

Race Metadata

datestring

Race date (YYYY-MM-DD)

trackstring

Track name (display format)

raceNumberinteger

Race number

raceNamestring | omitted

Official race name

distancestring | omitted

Race distance (e.g. "2000m")

conditionstring | omitted

Track condition (e.g. "Good 4"). Often absent pre-race.

weatherstring | omitted

Weather at time of race

raceClassstring | omitted

Race class/grade (e.g. "BM78", "Group 1")

startTimestring | omitted

Scheduled start time in UTC (ISO 8601, e.g. "2026-01-15T03:30:00Z"). Use timezone to convert to local venue time.

timezonestring | omitted

Venue timezone (e.g. "Australia/Sydney")

prizeMoneystring | omitted

Race prize money/purse

abandonedboolean

Whether this race has been abandoned (cancelled)

numberOfRunnersinteger

Total entries in runners, including scratchings — not the number that will contest the race. Count runners with scratched: false for that.

Runner Fields

runners[].numberinteger

Saddle cloth number

runners[].namestring

Runner name

runners[].jockeystring | omitted

Jockey/driver name

runners[].trainerstring | omitted

Trainer name

runners[].weightnumber | omitted

Allocated handicap weight (kg)

runners[].claimnumber | omitted

Apprentice weight claim (kg). Omitted for the majority of runners, who carry no claim.

runners[].barrierinteger | omitted

Barrier draw position (box number for greyhounds). For harness, the place within the runner's row (startRow) or at its handicap mark (handicapMetres).

runners[].startRowstring | omitted

Harness only: the row the runner starts from, front or second. Together with barrier it is the start — second with barrier 1 is Sr1. Omitted for back-markers in a standing start and outside harness.

runners[].unrulyboolean | omitted

Harness only: true when the runner is drawn in an unruly place in its row or at its mark (FrU3, 20m U1).

runners[].handicapMetresinteger | omitted

Harness standing starts: metres behind the front mark (e.g. 20); barrier is then the place at that mark. Omitted on mobile starts and for front-mark runners.

runners[].ageinteger | omitted

Runner age

runners[].sexstring | omitted

Sex (e.g. "Gelding", "Mare", "Filly", "Colt", "Dog", "Bitch")

runners[].sirestring | omitted

Sire (father)

runners[].damstring | omitted

Dam (mother)

runners[].countrystring | omitted

Country of origin, 2-letter lowercase ISO code (e.g. "au", "nz", "gb")

runners[].careerPrizeMoneystring | omitted

Career prize money earned. Raw string from the source, so it may carry a currency symbol.

runners[].formstring | omitted

Short form string — the runner's last 5 starts, most recent last. Digits are finishing positions (0 means 10th or worse) and X denotes a spell.

runners[].last20Startsstring | omitted

Extended form string covering the runner's last 20 starts, same encoding as form. form is its trailing 5 characters, so this is the one to read for full history.

runners[].scratchedboolean

Whether the runner is scratched

Career Stats (all tiers)

runners[].stats.overallobject

Career totals: starts, wins, seconds, thirds, places, winPercent, placePercent

runners[].stats.trackobject

Stats at this track: starts, wins, seconds, thirds, places, winPercent, placePercent

runners[].stats.distanceobject

Stats at this distance: starts, wins, seconds, thirds, places, winPercent, placePercent

runners[].stats.trackDistanceobject

Stats at this track + distance: starts, wins, seconds, thirds, places, winPercent, placePercent

runners[].stats.conditionsobject

Stats for every track condition the runner has raced on, keyed by condition. Gallops use good, soft, heavy, firm, synthetic; harness and greyhounds also report fast and slow. Each value: starts, wins, seconds, thirds, places, winPercent, placePercent. Use this race's condition to pick the relevant entry.

Spell Stats (all tiers)

runners[].stats.firstUpobject | omitted

Performance first-up from a spell. Gallops and harness only — never present for greyhounds, and omitted where the runner has no spell history.

runners[].stats.secondUpobject | omitted

Performance second-up from a spell. Same availability as firstUp.

Pro Enrichments

runners[].decoratorsarray | omitted

Contextual form badges computed for this race. Present on Pro (an empty array if the runner earned none), omitted entirely on Free. See Form Badges.

runners[].speedMapobject | omitted

Running style, early speed index and settling position, built from the runner's past in-running positions. What each field is built from differs by race code — for harness the early speed index is draw-adjusted and the settling position is the bell. Omitted for runners we can't rate. See Speed Map.

runners[].classProfileobject | omitted

Class history: current/peak rating, optimal range, and trend. See Class Profile.

runners[].raceClassFitobject | omitted

How the runner's class level compares to this race. See Class Profile & Race Fit.

Example Response

Fields marked Pro are absent from the response on the Free tier — the keys are removed, not set to null.

200

Response

json

{
  "date": "2026-01-15",
  "track": "Flemington",
  "raceNumber": 7,
  "raceName": "Lexus Handicap",
  "distance": "2000m",
  "condition": "Good 4",
  "weather": "Fine",
  "raceClass": "BM78",
  "startTime": "2026-01-15T03:30:00Z",
  "timezone": "Australia/Melbourne",
  "prizeMoney": "300000",
  "abandoned": false,
  "numberOfRunners": 12,
  "runners": [
    {
      "number": 1,
      "name": "Star Runner",
      "jockey": "J. McDonald",
      "trainer": "C. Waller",
      "weight": 58.5,
      "barrier": 5,
      "age": 4,
      "sex": "Gelding",
      "sire": "Written Tycoon",
      "dam": "Amelie's Star",
      "country": "au",
      "careerPrizeMoney": "845000",
      "form": "32141",
      "last20Starts": "43221121X32141",
      "scratched": false,
      "stats": {
        "overall": {
          "starts": 20, "wins": 8, "seconds": 4,
          "thirds": 3, "places": 15,
          "winPercent": 0.40, "placePercent": 0.75
        },
        "track": {
          "starts": 5, "wins": 3, "seconds": 1,
          "thirds": 0, "places": 4,
          "winPercent": 0.60, "placePercent": 0.80
        },
        "distance": {
          "starts": 8, "wins": 4, "seconds": 1,
          "thirds": 1, "places": 6,
          "winPercent": 0.50, "placePercent": 0.75
        },
        "trackDistance": {
          "starts": 3, "wins": 2, "seconds": 0,
          "thirds": 1, "places": 3,
          "winPercent": 0.667, "placePercent": 1.0
        },
        "conditions": {
          "good": {
            "starts": 6, "wins": 3, "seconds": 1,
            "thirds": 1, "places": 5,
            "winPercent": 0.50, "placePercent": 0.833
          },
          "soft": {
            "starts": 4, "wins": 1, "seconds": 0,
            "thirds": 1, "places": 2,
            "winPercent": 0.25, "placePercent": 0.50
          }
        },
        "firstUp": {
          "starts": 4, "wins": 2, "seconds": 1,
          "thirds": 0, "places": 3,
          "winPercent": 0.50, "placePercent": 0.75
        },
        "secondUp": {
          "starts": 4, "wins": 1, "seconds": 1,
          "thirds": 1, "places": 3,
          "winPercent": 0.25, "placePercent": 0.75
        }
      },
      "decorators": [
        {
          "type": "last_start_winner",
          "label": "Last Start Winner",
          "shortLabel": "Winner",
          "category": "form",
          "sentiment": "+",
          "description": "Won their most recent start",
          "detail": "Won by 2.5L at Flemington"
        }
      ],
      "speedMap": {
        "runningStyle": "P",
        "earlySpeedIndex": 6.2,
        "settlingPosition": 3.5
      },
      "classProfile": {
        "currentRating": 72,
        "peakRating": 85,
        "highestClassWon": 75,
        "optimalRangeMin": 65,
        "optimalRangeMax": 85,
        "trend": "stable"
      },
      "raceClassFit": {
        "raceClassRating": 72,
        "classDifference": 0,
        "withinOptimalRange": true,
        "assessment": "comfort_zone"
      }
    }
  ]
}