GUgumnut-ai
people

List people in a library

Changed on

Returns a paginated list of person records, which may be named or unnamed and may have zero or more faces, ordered according to sort (newest first by default), optionally filtered by asset, album, name, or ID.

By default only named people who are not hidden are returned; pass name_filter=all to include unnamed people (or name_filter=unnamed for only those), and include_hidden=true to include hidden people.

To list the underlying faces for a specific person, use list_faces with person_id.

Pagination is cursor-based: when has_more is true, pass the id of the last person in data as starting_after_id to fetch the next page.

get/api/people

Request

  • Base URL
    https://api.gumnut.ai
  • Auth
    • HTTP bearer
    • or HTTP bearer

Query parameters

limitinteger

Maximum number of people to return per page (1–200). Defaults to 20.

starting_after_idstring nullable

Cursor for pagination. Pass the id of the last person in the previous response's data to fetch the next page. Omit for the first page.

asset_idstring nullable

Return only people in this asset, by a face or a body linked to them. Useful for 'who is in this photo?'.

album_idstring nullable

Return only people who appear in at least one asset of this album, by a face or a body linked to them. Useful for 'who is in this album?'.

idsstring[] nullable

Look up specific people by ID (max 200; each ID has the person_ prefix). Accepts multiple ids= query params or a single comma-delimited value (e.g., ids=person_1,person_2). When set, name_filter defaults to all and include_hidden defaults to true so unnamed and hidden people are included in the lookup.

namestring nullable

Filter by name using case-insensitive substring matching. Use this to resolve a user-supplied name like 'Alice' into a person_id, then pass that ID into search_assets.person_ids or list_assets.person_ids.

name_filter'named' | 'unnamed' | 'all'

Which people to include, based on name nullness: named returns people whose name is non-null; unnamed returns people whose name is null; all returns both.

Filter by name nullness. Defaults to named (non-null names), or all when ids is provided.

include_hiddenboolean nullable

Include people marked hidden (is_hidden). Defaults to false, or to true when ids is provided, so lookups by ID still return hidden people.

sort'created_at_desc' | 'created_at_asc' | 'name_asc' | 'name_desc' | 'asset_count_desc' | 'asset_count_asc'

Sort orders for list_people. Each value encodes column + direction; decompose via the column and direction properties.

Sort order for results: created_at_desc (newest people first; default) / created_at_asc, name_asc / name_desc (alphabetical by name, locale-aware; unnamed people always sort last), or asset_count_desc / asset_count_asc (by number of photos the person appears in). Name sorts cannot be combined with name_filter=unnamed.

library_idstring nullable

Library to list from. Optional if the user has a single live (non-trashed) library; required when they have multiple.

includestring[] nullable

Opt-in expansion fields. Supported values: cluster_metrics (adds the nested cluster_metrics object — pairwise_p90, pairwise_mean, face_count — for each Person with a populated centroid). Accepts multiple include= query params or a single comma-delimited value. Unknown values return 422.

Response

Successful Response

has_moreboolean required

True if there are more people after this page. Pass the last person's id as starting_after_id to fetch the next page.

Changes

  • 7c2860d9eb88Revision changes
    • info

      added the new optional query request parameter include_hidden

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

  • 815e0302a988Revision changes
    • breaking

      response property detail list-of-types was widened by adding types string to media type application/json of response 422

    • info

      the response property became required for the status