> ## Documentation Index > Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get a person > 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`. ## OpenAPI ````yaml https://api.gumnut.ai/openapi.json get /api/people/{person_id} openapi: 3.1.0 info: title: Gumnut API description: API for using Gumnut to manage photos and videos version: 0.1.0 servers: [] security: [] paths: /api/people/{person_id}: get: tags: - people summary: Get a person description: >- 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`. operationId: get_person parameters: - name: person_id in: path required: true schema: type: string description: >- 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`). title: Person Id description: >- 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`). - name: include in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Opt-in expansion fields. See `list_people` for supported values. Accepts multiple `include=` query params or a single comma-delimited value. title: Include description: >- Opt-in expansion fields. See `list_people` for supported values. Accepts multiple `include=` query params or a single comma-delimited value. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PersonResponse' '404': description: Not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: PersonResponse: properties: id: type: string title: Id description: Unique person identifier with 'person_' prefix name: anyOf: - type: string - type: 'null' title: Name description: Optional name assigned to this person birth_date: anyOf: - type: string format: date - type: 'null' title: Birth Date description: Optional birth date of this person is_hidden: type: boolean title: Is Hidden description: Whether this person should be hidden from the UI is_favorite: type: boolean title: Is Favorite description: Whether this person is marked as a favorite asset_count: anyOf: - type: integer - type: 'null' title: Asset Count description: >- Number of unique photos this person appears in, or null if not computed thumbnail_face_id: anyOf: - type: string - type: 'null' title: Thumbnail Face Id description: ID of the face resource used as this person's thumbnail asset_urls: anyOf: - additionalProperties: $ref: '#/components/schemas/AssetVariant' type: object - type: 'null' title: Asset Urls description: >- 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: anyOf: - $ref: '#/components/schemas/ClusterMetricsResponse' - type: 'null' description: >- Cohesion metrics for this person's face cluster. Populated only when `include=cluster_metrics` is requested on the people endpoint, and only for persons with a populated centroid (newly-created empty Persons will have null). See `ClusterMetricsResponse` for the shape. created_at: type: string format: date-time title: Created At description: When this person record was created updated_at: type: string format: date-time title: Updated At description: When this person record was last updated type: object required: - id - is_hidden - is_favorite - created_at - updated_at title: PersonResponse description: Represents a person identified through face clustering and recognition. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AssetVariant: properties: url: type: string title: Url description: URL to fetch this image variant mimetype: type: string title: Mimetype description: MIME type of the served image width: anyOf: - type: integer - type: 'null' title: Width description: Target width in pixels (null if unknown) type: object required: - url - mimetype title: AssetVariant description: A single image variant with its URL, MIME type, and target width. ClusterMetricsResponse: properties: pairwise_p90: type: number title: Pairwise P90 description: >- 90th-percentile pairwise cosine distance between faces in this person's cluster. Lower = more cohesive cluster; loose clusters (higher pairwise_p90) are gated out of the face-assignment path to prevent further drift. pairwise_mean: type: number title: Pairwise Mean description: >- Mean pairwise cosine distance between faces in this person's cluster. face_count: type: integer title: Face Count description: >- 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 (one asset can contribute multiple faces of the same person). type: object required: - pairwise_p90 - pairwise_mean - face_count title: ClusterMetricsResponse description: |- 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) and drive both the production face-assignment cohesion gate and the operator-facing face cleanup dashboard. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError ````