---
title: "Get what every paddock and mob on a property is under"
method: GET
path: "/farms/{farm_id}/status"
tags: ["Farms"]
---

# Get what every paddock and mob on a property is under

`GET /farms/{farm_id}/status`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/farms/{farm_id}/status`
- Auth: HTTP bearer

The current status of every active paddock and mob on one property, from a single read: the
call the property map colours its assets by, and the one an assistant uses to ask what is under
withholding across the whole property without reading every paddock and mob. Archived assets
are left out.

A status is **derived on read** from the completed records on the asset, never stored, by the
same function that fills `withholding` on `getMob` and `getPaddock`, so the two always agree:

* A **mob** is held back by the meat withholding period (WHP) and the export slaughter interval
  (ESI) on the product lines of its completed treatment **and** husbandry records, so a 6-in-1
  given at marking counts like a drench. `state` is `under_withholding` while the meat WHP is
  running, `under_export_withholding` while only the ESI is, and `clear` otherwise.
* A **paddock** is held back by the grazing and harvest withholding periods on its completed
  sprays and on the seed treatments of a completed sowing. `state` is `graze_restricted` while a
  grazing WHP is running, `harvest_restricted` while only a harvest WHP is, and `clear`
  otherwise. **Fertiliser and field work never change a paddock's status**; a fertiliser's
  advisory note is advice, not a status. A spray label that says DO NOT graze is recorded on the
  spray (`spray.products[].do_not_graze`) but gives the paddock no status, since it has no date.

Within each asset the status is the **latest end date of each kind across every record still
under an interval**, not just the newest record. Only records completed in the last 12 months
are read. `withholding` is null when the asset is clear.

Plain JSON, not JSON:API. Needs read access to the property's records: any member of the
owning business (a viewer included) or the person on a personal property, and an assistant
within its read grant. A property shared publicly or by link does NOT share its status. Not
cached.

## Path parameters

- `farm_id` string, required

## Response `200`

Every active mob and paddock with its state and, when held back, its withholding.

- FarmStatusResponse: The status of every active mob and paddock on a property, as of today.
  - `farm_id` string
  - `as_of` string, date: The day the dates were compared against, in the server's time zone.
  - `mobs` FarmStatusMob[]
    - `id` string
    - `state` 'clear' | 'under_withholding' | 'under_export_withholding'
    - `withholding` MobWithholding, nullable: What is holding a mob back, or null when it is clear: the latest end of each interval across the completed treatment and husbandry records still under one. Dates are ISO 8601. `task_id` and `record_id` name the record that ends last; `products` is every named product still holding the mob back.
      - `task_id` string
      - `record_id` string
      - `safe_for_slaughter_on` string, nullable: The latest end of any meat withholding period, or null when none is stated.
      - `export_eligible_on` string, nullable: The latest end of any export slaughter interval, or null when none is stated.
      - `products` string[]
  - `paddocks` FarmStatusPaddock[]
    - `id` string
    - `state` 'clear' | 'graze_restricted' | 'harvest_restricted'
    - `withholding` PaddockWithholding, nullable: What is holding a paddock back, or null when it is clear: the latest end of each interval across the completed sprays and seed treatments still under one. Dates are ISO 8601. `task_id` and `record_id` name the record that ends last; `products` is every named product still holding the paddock back. Fertiliser and field work never appear here.
      - `task_id` string
      - `record_id` string
      - `safe_to_graze_on` string, nullable: The latest end of any grazing withholding period, or null when none is stated.
      - `safe_to_harvest_on` string, nullable: The latest end of any harvest withholding period, or null when none is stated.
      - `products` string[]

## Other responses

- `401`: Unauthenticated
- `403`: Not a member of this property's business.
- `404`: No such property.

---

[API](https://skmtc.dev/purplegrain/apis/purple-grain-api.md) · [All operations](https://skmtc.dev/purplegrain/apis/purple-grain-api/llms.txt) · [OpenAPI document](https://skmtc.dev/purplegrain/apis/purple-grain-api/revisions/06540345bbbc?raw)