Docs
Docs pages

API reference

POST /v1/health-score Preview / off

One number from 0 to 100 per animal, rolled up from the state readings. It is null unless a validated state reading exists, and it is always labelled ESTIMATE.

Not veterinary advice. No state reading has passed a locked test yet, so the score is null for every animal today. The endpoint exists so you can build against its shape. The unvalidated readings are returned under states with validated: false; do not act on them as findings.

Request

Send a video the same way as /v1/analyze (raw bytes, or video_b64 in JSON), with the same options: species, max_seconds, start_s, step_s. Or pass sample to get a stored result of a real run with no video: nothing is metered and the response says "sample": true.

curl -s -X POST "https://vitalsbio-console.pages.dev/api/v1/health-score?sample=cow-lying" \
  -H "Authorization: Bearer $VITALSBIO_API_KEY"

curl -s "https://vitalsbio-console.pages.dev/api/v1/health-score?species=cattle&max_seconds=20" \
  -H "Authorization: Bearer $VITALSBIO_API_KEY" -H "Content-Type: video/mp4" \
  --data-binary @barn.mp4

Samples: cow-lying, dog-walk, brangus-herd, paddock, white-horses. This endpoint runs the same model call as /v1/analyze and is metered the same way, by seconds of video. If you need more than one part of the same clip, call /v1/analyze once.

Response

FieldWhat it is
capabilityThe status of this part: live (passed its locked test), preview, pending or off. Read it before you rely on the numbers.
sampletrue when the answer is a stored result, not a run on your video.
animals[].score0 to 100, higher is better. null when no state reading for this animal is validated. Today that is every animal.
animals[].labelAlways ESTIMATE: the roll-up itself has no test.
animals[].based_onWhich validated readings went into the score.
animals[].reasonWhy the score is what it is, in a sentence.
animals[].statesThe raw readings (calm, stressed, in_pain, lame, likely_unwell), each with p, validated, basis and a label.
usage.video_secondsSeconds of video metered for this call. Also in the X-Vitals-Video-Seconds header.
request_id, api_versionAlso in the X-Request-Id and Vitals-Version headers.

This is the real answer for sample=cow-lying, cut short:

{
  "object": "health-score",
  "request_id": "req_Lr0d1sY2rE9q",
  "api_version": "2026-11-21",
  "schema_version": "biomodel-v0.1",
  "capability": {
    "id": "states",
    "name": "Calm, stressed, in pain, likely unwell",
    "status": "off",
    "mode": "off",
    "label": "Preview / off"
  },
  "sample": true,
  "video": {
    "fps": 25,
    "width": 1920,
    "height": 1080,
    "n_frames": 689,
    "step_s": 0.2
  },
  "model": {
    "name": "vitals-biomodel",
    "version": "biomodel-v0.1"
  },
  "animals": [
    {
      "track_id": 1,
      "species": "cattle",
      "score": null,
      "label": "ESTIMATE",
      "validated": false,
      "based_on": [],
      "reason": "No validated state reading exists for this animal, so no score is given. The unvalidated readings are in `states`.",
      "states": {
        "calm": {
          "p": 0.908,
          "validated": false,
          "basis": "1 - stressed (hand-set rule on 27 s: motion p90 0.25 body sizes/s, sudden changes 5% of steps; not fitted, not validated)",
          "label": "ESTIMATE"
        },
        "likely_unwell": {
          "p": 0.212,
          "validated": false,
          "basis": "hand-set rule on 27 s: lying 96% (behaviour head p(lying)), moving 10%, nearest animal 0.6 body sizes away; no own-normal baseline (needs days), not validated",
          "label": "ESTIMATE"
        }
      }
    }
  ],
  "usage": {
    "video_seconds": 0
  }
}

Errors, limits and headers are the same on every endpoint: see errors and rate limits. For a long video or a camera, see streaming.