---
title: "Every dog in one greyhound race with its recent runs, from our own results"
method: GET
path: "/v1/racing/greyhounds/field"
tags: ["Racing"]
---

# Every dog in one greyhound race with its recent runs, from our own results

`GET /v1/racing/greyhounds/field`

## Request

- Base URL: `https://api.puntersedge.online`
- URL: `https://api.puntersedge.online/v1/racing/greyhounds/field`
- Auth: API key in header `X-API-Key`

Cost: 3 credits. Every dog in one greyhound race with its recent runs from our own results, in
one call: the field's form, not one dog's. Australian races and, from 12 October 2026, British
and Irish ones.

**Naming the race.** `race_id` from /v1/racing/next-to-go, /events or /results is exact. Failing
that, `venue` + `meeting_date` + `race_number`: the AET meeting date for an Australian race, the
London date for a British or Irish one, the track matched by words there ("Towcester" finds
"Betway Towcester"). Only greyhound races are matched, so a track that races dogs and trots on
the same day is not ambiguous (from 13 October 2026); two greyhound races sharing those three
answer 409 `race_ambiguous` and cost nothing.

**The field.** While the race is open the runners come from the live card (`card_source: live`):
rug number, trap, trainer and the card's form figures as the books publish them -- PointsBet on
every card, William Hill on the British and Irish ones -- with a dog the card has since scratched
kept in the field and marked `scratched: true`. Once the race has been run and the live card
purged, the field is the settled result's (`card_source: results`).

**The runs.** Under each dog, its newest `runs` runs (default 10, at most 20) and a starts, wins
and places summary over every run held, ONLY RUNS BEFORE THIS RACE'S START (`form_as_at`), so a
race already run answers with what was knowable at the jump and never with its own result. On an
Australian race the runs are the same store /v1/racing/greyhounds/form reads -- our own collected
results and the history behind them, with times, splits, weight, PIR and grade where the source
printed them. On a British or Irish race they are our own GB/IE results from PointsBet's settled
race card since 12 October 2026: the paid places carry a `position` (three on a six-dog field),
every other starter reads `ran` with `position` null -- not placed, which covers a dog that did
not finish, and `source.note` says so on every British or Irish answer -- and there are no times,
splits or grades;
`source.region` reads `GB-IE` and `source.coverage_from` is that floor, so most dogs hold few or
no runs yet -- British dogs race about weekly, and the record grows with every meeting we settle.
`runs_total` counts STARTS (`status: ran`), the same figure as `stats.starts`, and
`held_rows_total` every held row, scratchings and unused reserves included, which is what `runs`
is drawn from; before 2026-10-13 `runs_total` counted every row.

**Identity.** Dogs are grouped on `name_key`, the name's letters and digits, the same fold the
one-dog routes use; pass it as `dog` there for the full record. A race we cannot find is a free
404, a race we hold no field for a free 404, an unknown query parameter a free 422. Greyhounds
only; thoroughbreds have /v1/racing/form. Cached 10 minutes; the Australian store refreshes
hourly, the British and Irish runs are read live.

## Query parameters

- `race_id` string, nullable: The race_id from /v1/racing/next-to-go, /events or /results. The primary form; use venue + meeting_date + race_number only when you do not hold it.
- `venue` string, nullable: Track name as the feeds spell it (case-insensitive; a British or Irish track is matched by words). Needs meeting_date and race_number.
- `meeting_date` string, date, nullable: Meeting date, YYYY-MM-DD: the AET date for an Australian race, the London date for a British or Irish one.
- `race_number` integer, nullable
- `runs` integer: Most recent runs to return per dog. The stats cover every held run regardless.

## Headers

- `X-API-Key` string
- `X-RapidAPI-Proxy-Secret` string

## Response `200`

Successful Response

- GreyhoundFieldOut
  - `race_id` string, required
  - `venue` string, nullable
  - `race_number` integer, nullable
  - `start_time` string, nullable: Scheduled start, UTC.
  - `meeting_date` string, nullable: Sydney calendar date of the meeting; the London date for a British or Irish race.
  - `race_name` string, nullable
  - `distance_m` integer, nullable
  - `track_condition` string, nullable
  - `race_status` string, nullable: The live race's status while it is open; the result's (`interim`/`final`) once it has been run.
  - `card_source` string, required: `live` -- the field came from the live card; `results` -- the race has been run, its live rows are gone, and the field is the settled result's.
  - `form_as_at` string, nullable: This race's start, UTC. Every run and figure below is from BEFORE this instant, so a race already run answers with what was knowable at the jump, never its own result.
  - `runs_per_runner` integer, required
  - `runners_total` integer, required
  - `runners_with_runs` integer, required: Runners with at least one start held (`runs_total` of 1 or more). A runner whose only held rows are scratchings or unused reserves is not counted.
  - `runners` GreyhoundFieldRunner[], required
    - `number` integer, nullable: Rug number on this race's card.
    - `name` string, required: The dog's name as the card (or the result) spells it.
    - `name_key` string, required: The identity the runs were grouped on (letters and digits). Pass it, or the name, as `dog` to /v1/racing/greyhounds/form or /stats for the one-dog view.
    - `box` integer, nullable: Trap drawn for THIS race: the book's draw where it gives one, else the rug number (on a British or Irish card the two are the same number).
    - `trainer` string, nullable
    - `form` string, nullable: The card's form figures as the bookmaker prints them (William Hill and PointsBet on British and Irish cards; PointsBet on Australian ones). Null on a race answered from its result.
    - `scratched` boolean: True when the card has scratched the dog, or it is an unused reserve. It stays in the field.
    - `runner_ref` string, nullable: Registry id (grv:/grsa:) carried by a settled Australian result; null on a live card and on every British or Irish race.
    - `runs_total` integer, required: STARTS we hold for this dog BEFORE this race's start: runs with `status` `ran`, the same count as `stats.starts`. A scratching or an unused reserve is not a start. 0 is honest: a first starter, or a record older than `source.coverage_from`. Before 2026-10-13 this counted every held row; that count is `held_rows_total`.
    - `held_rows_total` integer, required: Every row we hold for this dog before this race's start: its starts plus its scratchings and unused reserves (rows whose `status` is not `ran`). `runs` is drawn from these rows, so a dog with `runs_total` 0 can still carry `runs` entries. Measured 2026-10-13: 6,247 of the AU store's 103,553 rows were not starts.
    - `stats` GreyhoundFieldStats, required
      - `starts` integer, required
      - `wins` integer, required
      - `places` integer, required: Finishes in the first three, wins included.
      - `win_pct` number, required
      - `place_pct` number, required
    - `runs` GreyhoundRun[], required: Newest first, at most `runs` of them, every one before this race's start. Scratchings and unused reserves are included and say so in `status`.
      - `date` string, nullable: Sydney calendar date of the race; the London date on a British or Irish run.
      - `start_time` string, nullable: Scheduled start, UTC.
      - `venue` string, nullable
      - `race_number` integer, nullable
      - `distance_m` integer, nullable
      - `race_name` string, nullable
      - `track_condition` string, nullable
      - `box` integer, nullable
      - `number` integer, nullable: Rug number; equals box for a starter.
      - `position` integer, nullable: Finishing place. Null when the dog did not run (see `status`) or did not complete the course. On a British or Irish run the positions are placings, so null with `status: ran` means not placed (see `source.note` on /v1/racing/greyhounds/field).
      - `status` string, nullable: `ran`, `scratched`, or `reserve` (a rug 9/10 reserve that never got a box).
      - `margin` string, nullable: Lengths behind the winner as the source printed it; the winner's own row carries the winning margin on Victorian tracks and null elsewhere.
      - `time_s` number, nullable: The dog's own finish time in seconds.
      - `first_split_s` number, nullable: First sectional in seconds, as the source page printed it. Null where it printed none — a reserve that never started has none, and some tracks publish no sectionals at all.
      - `second_split_s` number, nullable: Second sectional in seconds. Null on every Victorian run: FastTrack publishes one split, not two.
      - `weight_kg` number, nullable: Race-day weight in kilograms. Null where the page prints no weight — Western Australian meetings mostly print none (measured 2026-09-28 over 2026-09-13..28: Cannington 2.5%, Mandurah 15.4%, Northam 68.7% of runs).
      - `pir` string, nullable: Position in running as TEXT, one digit per in-running mark ("21" = 2nd then 1st at the marks; the finish is not a mark). Victorian runs: FastTrack's own PIR column. Other states, since 2026-09-29: the national page's In Race Positions card, which only some tracks print — measured 2026-09-28 over the 158 national races of 2026-09-27..28: NSW 79.6%, QLD 79.0%, WA 100% of runs, SA and TAS about 0% (no card at Angle Park, Gawler, Launceston, Rockhampton or Temora). The two sources' marks are not the same points on a track: compare PIR within one source. Null where the page printed none.
      - `grade` string, nullable: The race's grade in the SOURCE'S OWN WORDS — "M", "4/5", "FFA" on the national pages, a race type like "Tier 3 - Maiden" on FastTrack. The two vocabularies are NOT mapped onto each other and must not be compared across states. Null on runs whose field was stored before 2026-09-21.
      - `win_time_s` number, nullable: The winner's time in the same race, so `time_s - win_time_s` is the deficit.
      - `sp` number, nullable: Official starting price, decimal return on $1. Null = unknown, never zero.
      - `dead_heat` boolean
      - `trainer` string, nullable
      - `field_size` integer, nullable: Dogs that ran in that race.
      - `runner_ref` string, nullable: Registry id of the dog as the collector for that track numbers it: grv:<id> or grsa:<id>.
      - `source` string, nullable: `fasttrack` or `grsa` — which collector wrote the race; `pointsbetau` on a British or Irish run.
      - `origin` string, nullable: `results` — the race is one we settled and serve on /v1/racing/results; `history` — the race was read back off the same official results page by our history collector and has no results row.
      - `result_id` string, nullable: Id of the /v1/racing/results row this run came from. On an `origin: history` run it is a synthetic `hist:…` id that joins to nothing.
  - `source` GreyhoundFieldSource, required: The field view's source block: the per-dog one plus `note`. A subclass, so the per-dog routes' published shape does not change.
    - `feed` string: Where the data comes from: our own collection of published AU greyhound results, Victorian tracks via FastTrack (runner_ref grv:) and every other state via the national results pages (runner_ref grsa:). Runs on or after `results_from` are races we settled ourselves; earlier runs are the same pages read back by our history collector. Refreshed hourly. On a British or Irish race (/v1/racing/greyhounds/field, from 2026-10-12) `region` reads GB-IE and the runs are our own GB/IE results from PointsBet's settled race card, read live.
    - `region` string
    - `sport` string
    - `coverage_from` string: Sydney date of the OLDEST run in the store. A dog's record here starts here.
    - `results_from` string: Sydney date our own settled results begin. A run on or after it has `origin: results` and a `result_id` that joins to /v1/racing/results; an earlier one has `origin: history` and does not.
    - `coverage_to` string, nullable: Sydney date of the latest race in the store.
    - `collectors` string[]: Which of our collectors can contribute a run: `fasttrack` = Victorian tracks, `grsa` = every other state.
    - `refreshed_hourly` boolean: The store is rebuilt from our results at :58 each hour, after both collectors have written.
    - `note` string, nullable: Set on a British or Irish race: GB/IE positions are placings, so a `ran` run with a null position was not placed. Null on an Australian race.

## Other responses

- `401`: Missing or invalid API key. Send `X-API-Key`. See https://puntersedge.online/developers/errors
- `402`: Monthly credit allowance exhausted for this plan. Upgrade at https://puntersedge.online/api/pricing
- `404`: No race matched, or we hold no field for it. Nothing was charged.
- `409`: Two greyhound races share that venue, date and number (a venue split). Nothing was charged.
- `422`: The race was not named. Nothing was charged.
- `429`: Rate limit exceeded for this plan. Honour the `Retry-After` header (seconds) before retrying. See https://puntersedge.online/developers/rate-limits
- `500`: Unexpected server error. Safe to retry with backoff.

---

[API](https://skmtc.dev/puntersedge/apis/puntersedge-odds-api.md) · [All operations](https://skmtc.dev/puntersedge/apis/puntersedge-odds-api/llms.txt) · [OpenAPI document](https://skmtc.dev/puntersedge/apis/puntersedge-odds-api/revisions/f35b6aab1946?raw)