List people in a library
Returns a paginated list of people (named identities that group one or more faces), ordered according to sort (newest first by default), optionally filtered by asset, album, name, or ID. Use this to enumerate who appears in the library, to resolve a user-typed name to a person_id, or to find who appears in a specific asset or album.
By default only named people are returned; pass name_filter=all or name_filter=unnamed to include clusters that haven’t been named yet.
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.
Query Parameters
Maximum number of people to return per page (1–200). Defaults to 20.
1 <= x <= 200Cursor 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.
Return only people who have at least one face in this asset. Useful for 'who is in this photo?'.
Return only people who appear in at least one asset of this album. Useful for 'who is in this album?'.
Look up specific people by ID (max 100; 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 so unnamed clusters are included in the lookup.
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_id.
Filter by name status: named returns only people with a name; unnamed returns only nameless face clusters awaiting a name; all returns both. Defaults to named (or all when ids is provided).
named, unnamed, all 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.
created_at_desc, created_at_asc, name_asc, name_desc, asset_count_desc, asset_count_asc Library to list from. Optional if the user has a single library; required when they have multiple.
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.