---
title: "Get a person"
method: GET
path: "/api/people/{person_id}"
tags: ["people"]
---

# Get a person

`GET /api/people/{person_id}`

## Request

- Base URL: `https://api.gumnut.ai`
- URL: `https://api.gumnut.ai/api/people/{person_id}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Fetches one person's metadata by ID (name, asset count, thumbnail, etc.). Use this when you already have a `person_id`. The JSON response is metadata only; to get the photos that contain this person, use `search_assets` with `person_ids` or `list_assets` with `person_ids`.

## Path parameters

- `person_id` string, required: Person ID (with `person_` prefix) to fetch. Carried by the `person_id` field on a face and by the entries of an asset's `people` field (returned with `include=people`).

## Query parameters

- `include` string[], nullable: Opt-in expansion fields. See `list_people` for supported values. Accepts multiple `include=` query params or a single comma-delimited value.

## Response `200`

Successful Response

- PersonResponse: Represents a person identified through face clustering and recognition.
  - `id` string, required: Unique person identifier with 'person_' prefix
  - `name` string, nullable: Name assigned to this person, or null when unnamed. Names supplied as text on create or update are trimmed and must not be blank.
  - `birth_date` string, date, nullable: Optional birth date of this person
  - `is_hidden` boolean, required: Whether this person should be hidden from the UI
  - `is_favorite` boolean, required: Whether this person is marked as a favorite
  - `asset_count` integer, nullable: Number of unique photos this person appears in, by a face or a body linked to them, or null if not computed
  - `thumbnail_face_id` string, nullable: ID of the face resource used as this person's thumbnail
  - `asset_urls` object, nullable: Asset variants from this person's thumbnail face. May be null when embedded in an AssetResponse; use /api/people endpoints for full person data.
  - `cluster_metrics` ClusterMetricsResponse: Cohesion metrics for a Person's face cluster — surfaced via `include=cluster_metrics` on the people endpoints. These describe how tight the cluster is in embedding space (lower = more cohesive).
    - `pairwise_p90` number, required: 90th-percentile pairwise cosine distance between faces in this person's cluster. Lower = more cohesive cluster.
    - `pairwise_mean` number, required: Mean pairwise cosine distance between faces in this person's cluster.
    - `face_count` integer, required: Number of faces that fed into the centroid and pairwise metrics. This is the cluster-membership count, **not** the same as `asset_count` — `face_count` counts every face row, while `asset_count` counts distinct assets, including those linked by a body (one asset can contribute multiple faces of the same person).
  - `created_at` string, date-time, required: When this person record was created
  - `updated_at` string, date-time, required: When this person record was last updated

## Other responses

- `401`: Missing, invalid, or expired credentials.
- `403`: The credentials are valid but not authorized for this operation — for example an API key whose action or library scope excludes it, or a credential type this operation does not accept.
- `404`: Not found
- `409`: Clerk sign-in could not be associated with the existing account. Resolve the identity conflict before retrying sign-in; repeated requests with unchanged verification and identity state will not resolve it.
- `422`: Validation Error
- `429`: Rate limit exceeded, or too many of your requests are already in progress. Retry after the interval in the `Retry-After` header.
- `503`: Authentication provider temporarily unavailable. Retry sign-in later.

## Changes

- **2026-10-16** `7c2860d9eb88`: 2 info
  - added the non-success response with the status `409`
  - added the non-success response with the status `503`
- **2026-08-08** `815e0302a988`: 1 breaking, 1 info
  - response property `detail` list-of-types was widened by adding types `string` to media type `application/json` of response `422`
  - the response property `detail` became required for the status `422`
- **2026-08-05** `c3e15c78f2da`: 4 info
  - added the media type `application/json` for the response with the status `404`
  - added the non-success response with the status `401`
  - added the non-success response with the status `403`
  - added the non-success response with the status `429`
- **2026-05-13** `adbb9fcd3066`: 2 breaking
  - `query` request parameter `include` list-of-types was narrowed by removing types `string`
  - for the `query` request parameter `include`, the type of property `anyOf[subschema #1]/` was specialized from `string` to `array`

[Operation history](https://skmtc.dev/gumnut-ai/apis/gumnut-api/changes/api/people/:person_id/get.md)

---

[API](https://skmtc.dev/gumnut-ai/apis/gumnut-api.md) - [All operations](https://skmtc.dev/gumnut-ai/apis/gumnut-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gumnut-ai/apis/gumnut-api/revisions/f3baab78e588?raw)