---
title: "Get Animal"
method: GET
path: "/v1/farm/{farm_id}/animals/{animal_id}"
tags: ["animals"]
---

# Get Animal

`GET /v1/farm/{farm_id}/animals/{animal_id}`

## Request

- Base URL: `https://api.ranch.bot`
- URL: `https://api.ranch.bot/v1/farm/{farm_id}/animals/{animal_id}`
- Auth: HTTP bearer

Current animals HTTP operation. External credential scopes: read:animals; include_saved_births additionally requires read:records. Minimum farm role: READER. Production rate limit: 100 requests per 15-minute window per device account, 1000 per browser session, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429.

## Path parameters

- `farm_id` string, uuid, required
- `animal_id` string, uuid, required

## Query parameters

- `include_saved_births` boolean
- `birth_skip` integer
- `birth_take` integer

## Response `200`

Success

- object
  - `id` string, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `is_active` boolean, required
  - `farm_id` string, required
  - `metadata` unknown, required
  - `groups` Group[], required
    - `id` string, nullable, required
    - `farm_id` string, nullable, required
    - `description` string, nullable, required
    - `is_active` boolean, nullable, required
    - `name` string, nullable, required
    - `created_at` string, date-time, nullable, required
    - `updated_at` string, date-time, nullable, required
  - `animal_identifiers` AnimalIdentifier[], required
    - `id` string, nullable, required
    - `animal_id` string, nullable, required
    - `is_active` boolean, nullable, required
    - `is_primary` boolean, nullable, required
    - `type` string, nullable, required
    - `value` string, nullable, required
    - `created_at` string, date-time, nullable, required
    - `updated_at` string, date-time, nullable, required
  - `records` RecordWithItems[], required
    - `id` string, nullable, required
    - `applied_at` string, date-time, nullable, required
    - `description` string, nullable, required
    - `is_active` boolean, nullable, required
    - `name` string, nullable, required
    - `type` string, nullable, required
    - `created_at` string, date-time, nullable, required
    - `updated_at` string, date-time, nullable, required
    - `record_items` RecordItem[], required
      - `id` string, nullable, required
      - `description` string, nullable, required
      - `is_active` boolean, nullable, required
      - `metadata` unknown, required
      - `name` string, nullable, required
      - `created_at` string, date-time, nullable, required
      - `updated_at` string, date-time, nullable, required
  - `files` File[], required
    - `id` string, nullable, required
    - `is_active` boolean, nullable, required
    - `mime_type` string, nullable, required
    - `name` string, nullable, required
    - `size` integer, nullable, required
    - `url` string, nullable, required
    - `created_at` string, date-time, nullable, required
    - `updated_at` string, date-time, nullable, required
  - `saved_births` object: Present only when include_saved_births is requested. Access-filtered saved birth (litter) bundles for this animal as dam or offspring; offspring_inventory reports live inventory status separately from the immutable bundle facts. Pagination is local to this animal-history expansion; standalone `GET /v1/farm/{farm_id}/birth-events` remains `{ total, records }` with no `pagination`.
    - `total` integer: Full count of matching saved births, independent of the requested page.
    - `records` BirthEvent[]
      - `id` string, uuid, required
      - `farm_id` string, uuid, required
      - `request_id` string, uuid, required
      - `confirmation_hash` string, required
      - `created_by_user_id` string, uuid, required
      - `dam_id` string, uuid, required
      - `birth_date` string, date-time, required
      - `time_precision` string, nullable, required
      - `bundle` object, required
        - `input` BirthBundle, required
          - `dam_id` string, uuid, required
          - `birth_date` string, required
          - `time_precision` 'date_only' | 'morning' | 'afternoon' | 'evening' | 'night'
          - `total_born` integer: Explicitly reported biological total, including stillborn. Omit when unknown; never derived from offspring entries.
          - `dam_update` object
            - `kind` string
            - `notes` string
          - `maternal_observations` object[]
            - `date` string, required
            - `text` string, required
          - `lactation_observations` object[]
            - `date` string, required
            - `text` string, required
          - `offspring` object[]
            - `review_label` string, required: Temporary review label only; never an invented identifier.
            - `animal_id` string, uuid: Link an existing active farm animal instead of creating a profile.
            - `sex` 'male' | 'female' | 'unknown': Required when creating a profile; omit when linking an existing animal.
            - `inventory_status` 'CURRENT' | 'UNKNOWN' | 'SOLD' | 'DECEASED' | 'NOT_MANAGED': Required when creating a profile; omit when linking an existing animal.
            - `birth_weight` object
              - …
            - `vigor` object[]
              - …
            - `supplementation` object[]
              - …
          - `sire` object
            - `status` 'unknown' | 'presumed' | 'confirmed', required
            - `animal_id` string, uuid
            - `provenance` string
            - `confidence` number
          - `protocol` object
            - `claimed_name` string, required
            - `completed_date` string, required
            - `version_id` string, uuid
            - `offspring_labels` string[], required
          - `follow_up` object[]
            - `name` string, required
            - `due_date` string
            - `offspring_labels` string[], required
          - `group_ids` string[]: Explicitly reviewed current group memberships. Does not record movement.
          - `current_location` string: Explicitly reviewed current location only; does not create movement history.
          - `source_sms_id` string, uuid
          - `source_message_id` string, uuid
          - `evidence` object[]
            - `file_id` string, uuid, required
            - `media_id` string, uuid
            - `link_to_dam` boolean
            - `offspring_label` string
          - `unresolved` string[]
          - `additional_source_sms_ids` string[]
        - `review` object, required: The resolved dam, groups, protocol, evidence and unresolved facts reviewed before confirmation.
      - `record_id` string, uuid, required
      - `source_sms_id` string, uuid, nullable, required
      - `source_message_id` string, uuid, nullable, required
      - `agent_action_id` string, uuid, nullable, required
      - `created_at` string, date-time, required
      - `offspring` object[], required
        - `id` string, uuid, required
        - `birth_event_id` string, uuid, required
        - `animal_id` string, uuid, required
        - `review_label` string, required
        - `position` integer, required
        - `details` object, required
      - `tasks` FarmTask[], required
        - `id` string, uuid, required
        - `farm_id` string, uuid, required
        - `birth_event_id` string, uuid, required
        - `name` string, required
        - `status` 'TODO' | 'DONE' | 'CANCELLED', required
        - `due_date` string, date-time, nullable, required
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
        - `animals` object[]
          - `id` string, uuid, required
      - `record` object, required
        - `id` string, uuid, required
        - `subtype` 'BIRTH' | 'null', nullable
        - `revision` integer
        - `is_active` boolean
        - `type` string
        - `applied_at` string, date-time
        - `files` object[], required
          - `id` string, uuid, required
          - `name` string, required
          - `mime_type` string, required
      - `birth_details` object: Canonical record-first birth facts. birth_date is a derived YYYY-MM-DD projection of record.applied_at; the legacy timestamp remains for compatibility only.
        - `birth_date` string, date, required
        - `time_precision` string, nullable, required
        - `dam_id` string, uuid, required
        - `total_born` integer, nullable, required: Explicitly reported biological total; null means unknown and is never derived from offspring links.
        - `subtype` 'BIRTH' | 'null', nullable, required
        - `revision` integer, required
        - `lifecycle_status` 'active' | 'entered_in_error', required
        - `date_source` string, required
      - `care_records` object[], required
        - `id` string, uuid, required
        - `name` string, required
        - `applied_at` string, date-time, nullable, required
        - `record_items` object[], required
      - `sire_animals` object[]: Response-only identities for the selected sire and candidates from access-filtered breeding history, scoped to this farm. Includes inactive sires and active identifiers; never stored in the bundle or approval snapshot.
        - `id` string, uuid, required
        - `is_active` boolean, required
        - `metadata` object, nullable, required
        - `animal_identifiers` object[], required
          - `id` string, uuid
          - `type` string
          - `value` string
          - `is_active` boolean
      - `offspring_inventory` object[]: Response-only current-litter projection built only from active offspring links. Each entry reports live animal state, which is separate from the immutable captured birth facts in `offspring`/`bundle`. Inactive links (unlinked or entered-in-error) remain in historical `offspring` but are absent here; an active link to an archived, sold, deceased, or otherwise inactive animal is still reported with that live status. Animal activity is never used to filter the list.
        - `animal_id` string, uuid, required
        - `review_label` string, required
        - `position` integer, required
        - `inventory_status` 'CURRENT' | 'UNKNOWN' | 'SOLD' | 'DECEASED' | 'NOT_MANAGED' | 'null', nullable, required: The linked animal's current inventory status; null when the animal relation is unavailable.
        - `is_active` boolean, nullable, required: The linked animal's live is_active flag, not the link's; null when the animal relation is unavailable.
      - `linked_records` object[]: Response-only, deduplicated record links. A record linked more than once appears once, keyed by UUID; the primary birth record takes precedence over a care link with the same UUID.
        - `id` string, uuid, required
        - `kind` 'primary' | 'care', required
        - `name` string, nullable
        - `applied_at` string, date-time, nullable
        - `file_ids` string[]: Access-filtered file UUIDs for the primary record.
      - `media_file_ids` string[]: Unique, access-filtered file UUIDs referenced by the accepted birth evidence and the primary record.
    - `pagination` object: Present only on the animal-history expansion.
      - `skip` integer: Requested/default offset.
      - `take` integer: Requested/default page size.
      - `returned` integer: Number of records in this page.
      - `has_more` boolean: True when skip + returned is below total; never claims snapshot consistency across page requests.
      - `next_skip` integer, nullable: skip + returned when more remain, otherwise null.
  - `inventory_status` 'CURRENT' | 'UNKNOWN' | 'SOLD' | 'DECEASED' | 'NOT_MANAGED', required
  - `birth_facts` BirthFacts
    - `record` object, nullable, required
      - `record_id` string, required
      - `birth_event_id` string, required
      - `revision` number, required
      - `birth_date` string, required
      - `time_precision` string, nullable, required
      - `dam_id` string, required
      - `sire` BirthFactsSire, required
        - `status` 'unknown' | 'presumed' | 'confirmed', required
        - `animal_id` string, nullable, required
        - `provenance` string, nullable, required
        - `confidence` number, nullable, required
    - `derived` object, required
      - `birth_date` string, nullable, required
      - `time_precision` string, nullable, required
      - `dam_id` string, nullable, required
      - `sire` BirthFactsSire, required
        - `status` 'unknown' | 'presumed' | 'confirmed', required
        - `animal_id` string, nullable, required
        - `provenance` string, nullable, required
        - `confidence` number, nullable, required
    - `profile_birth_date` string, nullable, required
    - `effective_birth_date` string, nullable, required
    - `conflicts` object[], required
      - `independent_birth_date` string, required
      - `recorded_birth_date` string, required
      - `record_id` string, required

## Other responses

- `400`: Request validation failed.
- `401`: Missing/invalid authentication or insufficient farm role.
- `403`: Missing required scope or credential type is disallowed.
- `404`: Resource or active farm membership not found.
- `429`: Rate limit exceeded. Retry after the indicated delay.
- `500`: Unexpected server failure.

---

[API](https://skmtc.dev/ranch/apis/ranch-bot-http-api.md) · [All operations](https://skmtc.dev/ranch/apis/ranch-bot-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ranch/apis/ranch-bot-http-api/revisions/24109d33fa02?raw)