Skip to content

TutorialsLesson 11 of 15Products11 min read

AI-assisted tips: saved selections, explanations and settlement

Enterprise REST tutorial for /v1/tips, /v1/races/{raceId}/tip and its explanation endpoint: statuses, bet types, place terms, settlement and safe display.

  • List active saved selections
  • Read one race's selection and explanation
  • Display status, bet type and settlement accurately

Who can call the tips endpoints

The three REST tips endpoints require an active Enterprise plan; other plans receive 403. Website widgets on Professional can show a tips view inside the widget, but that is the widget product. It does not unlock the REST tips endpoints for a Professional key.

Tips are saved records, prepared daily from 06:00 UK time. Requesting them does not run AI on demand. You read a saved selection, its status and its explanation when available. Expected value is a model estimate, not a guaranteed profit; confidence is not a guarantee of winning. Only records with a selection and positive saved win-leg EV are exposed. A race may have no qualifying tip.

Listing active selections

GET/v1/tipsEnterprise

Saved selections for a day, filterable by status, paginated after filtering.

Use status=active for a current display. The filter runs before pagination, so meta.total counts matching records. Omit status to include other exposed selection records, such as settled, withdrawn or stale records; this is not the complete internal analysis history. Although the status filter accepts pending and no_selection, records without a selection and positive saved EV are not returned. Date defaults to today; set date to retrieve previously saved records. Tomorrow's selections are not prepared in advance and tomorrow=true is rejected.

async function activeTips(date) {
  const out = [];
  for (let page = 1; ; page++) {
    if (page > 1) await new Promise(resolve => setTimeout(resolve, 550));
    const url = new URL("/v1/tips", "https://racingapi.net");
    if (date) url.searchParams.set("date", date);
    url.searchParams.set("status", "active");
    url.searchParams.set("page", String(page));
    url.searchParams.set("limit", "100");
    const res = await fetch(url, { headers: { "X-API-Key": process.env.RACINGAPI_KEY } });
    const body = await res.json();
    if (res.status === 403) throw new Error("Enterprise access required");
    if (!res.ok) throw new Error(body.code);
    out.push(...body.data);
    if (page * body.meta.limit >= body.meta.total) return out;
  }
}

for (const tip of await activeTips()) {
  const s = tip.selection;
  const savedQuote = tip.odds[0]; // one saved quote, not necessarily the best
  console.log(tip.time, tip.course, s.horseName, tip.betType === "each_way" ? "Each way" : "To win",
    savedQuote ? (savedQuote.fractional || savedQuote.price) : "", tip.explanation ?? "");
}

One race: selection and explanation

GET/v1/races/{raceId}/tipEnterprise

The saved selection, evidence, silk path, odds, bet type and settlement for one race.

GET/v1/races/{raceId}/tip/explanationEnterprise

Only the saved two-sentence explanation and its version.

Replace {raceId} with an ID from a racecard or tip for the same date. Read status before displaying a selection. A missing or non-qualifying tip returns 404 tip_not_prepared; retrying does not generate one. The explanation endpoint returns the record's version, status and explanation, which can be null. Separate requests can observe different versions if a record changes between calls: use the full tip response when you need a consistent selection and explanation. Single-tip responses have data but no meta.

# Set RACE_DATE to the same YYYY-MM-DD used to discover RACE_ID.
curl --fail-with-body "https://racingapi.net/v1/races/$RACE_ID/tip?region=uk&date=$RACE_DATE" \
  -H "X-API-Key: $RACINGAPI_KEY"

curl --fail-with-body "https://racingapi.net/v1/races/$RACE_ID/tip/explanation?region=uk&date=$RACE_DATE" \
  -H "X-API-Key: $RACINGAPI_KEY"

Statuses, bet types and settlement

DiagramLifecycle of a saved selection
Lifecycle of a saved selection: step 1, Preparation; step 2, active; step 3, withdrawn / stale; step 4, settled.1 YOUR SERVERPreparation2 RACINGAPI.NETactive3 STOPwithdrawn / stale4 CACHEsettled
  1. 1Preparation. No qualifying saved selection means nothing to display.
  2. 2active. A selection with explanation and odds. Safe to display.
  3. 3withdrawn / stale. Remove from any active display.
  4. 4settled. Result confirmed; settlement holds outcome and position.
Display only active (and, in history views, settled) records.

Recommendation terms and widget colours are different things. Saved REST each-way terms specify three places at one fifth of the fractional win odds; read settlement against those saved terms. The widget colours an each-way finish green for the top three, or top four in fields of at least 16, while still showing the actual finishing position. Neither display rule guarantees a bookmaker payout: check the bookmaker's offered place terms.

FieldMeaning
betTypewin means To win; each_way means Each way.
placeTermsFor each-way tips: 3 places at one fifth of the odds. Null for win tips. Recommendation terms, not a bookmaker offer.
settlement.outcomewon, placed or lost against the saved terms, with position. Not an actual payout.
odds and oddsObservedAtBookmaker prices with their observation time. Show fractional when present, otherwise price.
expectedValueWin-leg EV only. Label it Win EV.
selectionScoreRanking score out of 100, not a confidence percentage.
Fields worth labelling carefully

Reference material

Exact schemas: API reference. First call: Quickstart. Copy-ready helpers: Code examples. Plans: Pricing.