---
title: "List Mobs"
method: GET
path: "/mobs"
tags: ["Mobs"]
---

# List Mobs

`GET /mobs`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/mobs`
- Auth: one of:
  - none
  - HTTP bearer

The mobs of one property (`farm_id`) or of every property in a farm
business (`organization_id`), ordered by name, case-insensitively.
With neither parameter the list is only the signed-in user's
personal-property mobs. A business's mobs are missing until you pass
`farm_id` or `organization_id`. `getFarmPicture` is every mob on one
property in one call.

A mob belongs to its property, not to a paddock: each one carries
`current_paddock_id`, the paddock it is in now (derived from its latest
completed move, null while it has never been placed). Move it with
`moveMob`.

Live mobs only by default — pass `archived=true` for the archive drawer
or `archived=all` for both. The default page holds a whole property's
mobs (200) so a client can render "2 placed · 1 unplaced" without a
second request; `meta` carries no total, so a truncated page is a wrong
number on screen rather than a missing row.

Any accepted member of the owning organization can list, a viewer
included.

## Query parameters

- `farm_id` string
- `organization_id` string
- `archived` string
- `page` integer
- `per_page` integer
- `include` string

## Response `200`

Mobs for the property or the business.

- MobsIndexResponseAttributes
  - `data` MobModelAttributes[]
    - `id` string
    - `type` string
    - `slug` string: Unique within its parent (a property per owner; a paddock or mob per property); generated from the name and renamed with it. The old slug keeps resolving. See `resolveLink`.
    - `web_path` string: The address on the web. Present when read directly.
    - `url` string: The whole link; carries the property's `?share=` token when it is shared by link. Present when read directly.
    - `name` string
    - `head_count` integer, nullable: How many head are in the mob, as a number — never a display string. Null is a real state.
    - `withholding` object, nullable: Is the mob under a withholding period or export slaughter interval right now? The latest drench record whose safe-for-slaughter or export date is still ahead, or null. **Derived, not stored.** Read-only.
      - `task_id` string
      - `record_id` string: The DrenchRecord id.
      - `safe_for_slaughter_on` string, date, nullable
      - `export_eligible_on` string, date, nullable
      - `products` string[]
    - `current_paddock_id` string, nullable: Where the mob is right now, derived from the most recent completed record carrying a destination (see `MobModel`). Read-only — move a mob with `moveMob`.
    - `archived` boolean: An archived mob leaves the map and the lists; its records stay on the property.
    - `archived_at` string, date-time, nullable
    - `record_count` integer: Completed rows on this mob — its diary.
    - `open_task_count` integer: Pending rows on this mob.
    - `last_record_at` string, date-time, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `farm` object: Present when include=farm
  - `meta` PaginationMeta
    - `current_page` number
    - `next_page` number, nullable
    - `prev_page` number, nullable

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found — neither `farm_id` nor `organization_id` names a record the caller can see.

---

[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/a9136f78e9fb?raw)