# Listing faces and associated users in a collection You can use the [ListFaces](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_ListFaces.html) operation to list faces and their associated users in a collection. For more information, see [Managing faces in a collection](managing-face-collections.md#collections-index-faces). **To list faces in a collection (SDK)** 1. If you haven't already: 1. Create or update a user with `AmazonRekognitionFullAccess` permissions. For more information, see [Step 1: Set up an AWS account and create a User](setting-up.md#setting-up-iam). 1. Install and configure the AWS CLI and the AWS SDKs. For more information, see [Step 2: Set up the AWS CLI and AWS SDKs](setup-awscli-sdk.md). 1. Use the following examples to call the `ListFaces` operation. ------ #### [ Java ] This example displays a list of faces in a collection. Change the value of `collectionId` to the desired collection. ``` //Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. //PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.) package aws.example.rekognition.image; import com.amazonaws.services.rekognition.AmazonRekognition; import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder; import com.amazonaws.services.rekognition.model.Face; import com.amazonaws.services.rekognition.model.ListFacesRequest; import com.amazonaws.services.rekognition.model.ListFacesResult; import java.util.List; import com.fasterxml.jackson.databind.ObjectMapper; public class ListFacesInCollection { public static final String collectionId = "MyCollection"; public static void main(String[] args) throws Exception { AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient(); ObjectMapper objectMapper = new ObjectMapper(); ListFacesResult listFacesResult = null; System.out.println("Faces in collection " + collectionId); String paginationToken = null; do { if (listFacesResult != null) { paginationToken = listFacesResult.getNextToken(); } ListFacesRequest listFacesRequest = new ListFacesRequest() .withCollectionId(collectionId) .withMaxResults(1) .withNextToken(paginationToken); listFacesResult = rekognitionClient.listFaces(listFacesRequest); List < Face > faces = listFacesResult.getFaces(); for (Face face: faces) { System.out.println(objectMapper.writerWithDefaultPrettyPrinter() .writeValueAsString(face)); } } while (listFacesResult != null && listFacesResult.getNextToken() != null); } } ``` ------ #### [ Java V2 ] This code is taken from the AWS Documentation SDK examples GitHub repository. See the full example [here](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/javav2/example_code/rekognition/src/main/java/com/example/rekognition/ListFacesInCollection.java). ``` // snippet-start:[rekognition.java2.list_faces_collection.import] import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.rekognition.RekognitionClient; import software.amazon.awssdk.services.rekognition.model.Face; import software.amazon.awssdk.services.rekognition.model.ListFacesRequest; import software.amazon.awssdk.services.rekognition.model.ListFacesResponse; import software.amazon.awssdk.services.rekognition.model.RekognitionException; import java.util.List; // snippet-end:[rekognition.java2.list_faces_collection.import] /** * Before running this Java V2 code example, set up your development environment, including your credentials. * * For more information, see the following documentation topic: * * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html */ public class ListFacesInCollection { public static void main(String[] args) { final String usage = "\n" + "Usage: " + " \n\n" + "Where:\n" + " collectionId - The name of the collection. \n\n"; if (args.length < 1) { System.out.println(usage); System.exit(1); } String collectionId = args[0]; Region region = Region.US_EAST_1; RekognitionClient rekClient = RekognitionClient.builder() .region(region) .credentialsProvider(ProfileCredentialsProvider.create("profile-name")) .build(); System.out.println("Faces in collection " + collectionId); listFacesCollection(rekClient, collectionId) ; rekClient.close(); } // snippet-start:[rekognition.java2.list_faces_collection.main] public static void listFacesCollection(RekognitionClient rekClient, String collectionId ) { try { ListFacesRequest facesRequest = ListFacesRequest.builder() .collectionId(collectionId) .maxResults(10) .build(); ListFacesResponse facesResponse = rekClient.listFaces(facesRequest); List faces = facesResponse.faces(); for (Face face: faces) { System.out.println("Confidence level there is a face: "+face.confidence()); System.out.println("The face Id value is "+face.faceId()); } } catch (RekognitionException e) { System.out.println(e.getMessage()); System.exit(1); } } // snippet-end:[rekognition.java2.list_faces_collection.main] } ``` ------ #### [ AWS CLI ] This AWS CLI command displays the JSON output for the `list-faces` CLI operation. Replace the value of `collection-id` with the name of the collection you want to list. Replace the value of `profile_name` in the line that creates the Rekognition session with the name of your developer profile. ``` aws rekognition list-faces --collection-id "collection-id" --profile profile-name ``` ------ #### [ Python ] This example displays a list of faces in a collection. Replace the value of `profile_name` in the line that creates the Rekognition session with the name of your developer profile. ``` # Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. # PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.) import boto3 def list_faces_in_collection(collection_id): maxResults = 2 faces_count = 0 tokens = True session = boto3.Session(profile_name='profile-name') client = session.client('rekognition') response = client.list_faces(CollectionId=collection_id, MaxResults=maxResults) print('Faces in collection ' + collection_id) while tokens: faces = response['Faces'] for face in faces: print(face) faces_count += 1 if 'NextToken' in response: nextToken = response['NextToken'] response = client.list_faces(CollectionId=collection_id, NextToken=nextToken, MaxResults=maxResults) else: tokens = False return faces_count def main(): collection_id = 'collection-id' faces_count = list_faces_in_collection(collection_id) print("faces count: " + str(faces_count)) if __name__ == "__main__": main() ``` ------ #### [ .NET ] This example displays a list of faces in a collection. Change the value of `collectionId` to the desired collection. ``` //Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. //PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.) using System; using Amazon.Rekognition; using Amazon.Rekognition.Model; public class ListFaces { public static void Example() { String collectionId = "MyCollection"; AmazonRekognitionClient rekognitionClient = new AmazonRekognitionClient(); ListFacesResponse listFacesResponse = null; Console.WriteLine("Faces in collection " + collectionId); String paginationToken = null; do { if (listFacesResponse != null) paginationToken = listFacesResponse.NextToken; ListFacesRequest listFacesRequest = new ListFacesRequest() { CollectionId = collectionId, MaxResults = 1, NextToken = paginationToken }; listFacesResponse = rekognitionClient.ListFaces(listFacesRequest); foreach(Face face in listFacesResponse.Faces) Console.WriteLine(face.FaceId); } while (listFacesResponse != null && !String.IsNullOrEmpty(listFacesResponse.NextToken)); } } ``` ------ ## ListFaces operation request The input to `ListFaces` is the ID of the collection that you want to list faces for. `MaxResults` is the maximum number of faces to return. ListFaces also takes in a list of face IDs to filter the results with, and a user ID provided to list only faces associated with the given user. ``` { "CollectionId": "MyCollection", "MaxResults": 1 } ``` If the response has more faces than are requested by `MaxResults`, a token is returned that you can use to get the next set of results, in a subsequent call to `ListFaces`. For example: ``` { "CollectionId": "MyCollection", "NextToken": "sm+5ythT3aeEVIR4WA....", "MaxResults": 1 } ``` ## ListFaces operation response The response from `ListFaces` is information about the face metadata that's stored in the specified collection. + **FaceModelVersion** – The version of the face model that's associated with the collection. For more information, see [Understanding model versioning](face-detection-model.md). + **Faces** – Information about the faces in the collection. This includes information about [BoundingBox](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_BoundingBox.html), confidence, image identifiers, and the face ID. For more information, see [Face](https://docs.aws.amazon.com/rekognition/latest/APIReference/API_Face.html). + **NextToken** – The token that's used to get the next set of results. ``` { "FaceModelVersion": "6.0", "Faces": [ { "Confidence": 99.76940155029297, "IndexFacesModelVersion": "6.0", "UserId": "demoUser2", "ImageId": "56a0ca74-1c83-39dd-b363-051a64168a65", "BoundingBox": { "Width": 0.03177810087800026, "Top": 0.36568498611450195, "Left": 0.3453829884529114, "Height": 0.056759100407361984 }, "FaceId": "c92265d4-5f9c-43af-a58e-12be0ce02bc3" }, { "BoundingBox": { "Width": 0.03254450112581253, "Top": 0.6080359816551208, "Left": 0.5160620212554932, "Height": 0.06347999721765518 }, "IndexFacesModelVersion": "6.0", "FaceId": "851cb847-dccc-4fea-9309-9f4805967855", "Confidence": 99.94369506835938, "ImageId": "a8aed589-ceec-35f7-9c04-82e0b546b024" }, { "BoundingBox": { "Width": 0.03094629943370819, "Top": 0.4218429923057556, "Left": 0.6513839960098267, "Height": 0.05266290158033371 }, "IndexFacesModelVersion": "6.0", "FaceId": "c0eb3b65-24a0-41e1-b23a-1908b1aaeac1", "Confidence": 99.82969665527344, "ImageId": "56a0ca74-1c83-39dd-b363-051a64168a65" } ] } ```