List people in a library
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 people with a non-null name are returned; pass name_filter=all for every person or name_filter=unnamed for people whose name is null.
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.
Maximum number of people to return per page (1–200). Defaults to 20.
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.
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.
Return only people who have at least one face in this asset. Useful for 'who is in this photo?'.
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?'.
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 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 so unnamed people are included in the lookup.
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 so unnamed people 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_ids.
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.
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.
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 to list from. Optional if the user has a single live (non-trashed) library; required when they have multiple.
Library to list from. Optional if the user has a single live (non-trashed) 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.
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