Percentile lookup

Updated Jul 17, 2026

Inverse of predict: given an observed measurement value, return its percentile in the modeled population.

POST/v1/percentile-lookup

Summary

Useful when you have a measured dimension and need to know where it sits relative to a population (P1–P99, one decimal place).

Cost: 1 credit or 1 free-tier call on success.

Request

Field	Type	Required	Notes
`measurement`	string	yes	Measurement name
`gender`	string	yes	`Male` or `Female`
`age`	number	yes	0–120
`value`	number	yes	Observed measurement in `unit`
`country`	string	no	Default `US`
`unit`	string	no	`mm`, `cm`, or `in`
`clothing`	string	no	Default `nude`
`posture`	string	no	Default `standing_erect`

Example

curl -sS https://api.humanform.app/v1/percentile-lookup \
  -H "Authorization: Bearer hf_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "measurement": "Stature",
    "gender": "Male",
    "age": 30,
    "country": "US",
    "unit": "mm",
    "value": 1750
  }'

{
  "measurement": "Stature",
  "gender": "Male",
  "age": 30,
  "country": "US",
  "unit": "mm",
  "value": 1750
}

Response

{
  "measurement": "Stature",
  "gender": "Male",
  "country": "US",
  "clothing": "nude",
  "posture": "standing_erect",
  "value": 1750,
  "unit": "mm",
  "percentile": 48.2
}

Notes

Values below the 1st or above the 99th percentile return 422 (value_below_percentile_range / value_above_percentile_range) and do not consume credits.
See Errors for the full error shape.