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.
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
| Field | What it is |
|---|---|
capability | The status of this part: live (passed its locked test), preview, pending or off. Read it before you rely on the numbers. |
sample | true when the answer is a stored result, not a run on your video. |
animals[].score | 0 to 100, higher is better. null when no state reading for this animal is validated. Today that is every animal. |
animals[].label | Always ESTIMATE: the roll-up itself has no test. |
animals[].based_on | Which validated readings went into the score. |
animals[].reason | Why the score is what it is, in a sentence. |
animals[].states | The raw readings (calm, stressed, in_pain, lame, likely_unwell), each with p, validated, basis and a label. |
usage.video_seconds | Seconds of video metered for this call. Also in the X-Vitals-Video-Seconds header. |
request_id, api_version | Also 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.