:doc:`Rekognition <../../rekognition>` / Client / list_faces

**********
list_faces
**********



.. py:method:: Rekognition.Client.list_faces(**kwargs)

  

  Returns metadata for faces in the specified collection. This metadata includes information such as the bounding box coordinates, the confidence (that the bounding box contains a face), and face ID. For an example, see Listing Faces in a Collection in the Amazon Rekognition Developer Guide.

   

  This operation requires permissions to perform the ``rekognition:ListFaces`` action.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/rekognition-2016-06-27/ListFaces>`_  


  **Request Syntax**
  ::

    response = client.list_faces(
        CollectionId='string',
        NextToken='string',
        MaxResults=123,
        UserId='string',
        FaceIds=[
            'string',
        ]
    )
    
  :type CollectionId: string
  :param CollectionId: **[REQUIRED]** 

    ID of the collection from which to list the faces.

    

  
  :type NextToken: string
  :param NextToken: 

    If the previous response was incomplete (because there is more data to retrieve), Amazon Rekognition returns a pagination token in the response. You can use this pagination token to retrieve the next set of faces.

    

  
  :type MaxResults: integer
  :param MaxResults: 

    Maximum number of faces to return.

    

  
  :type UserId: string
  :param UserId: 

    An array of user IDs to filter results with when listing faces in a collection.

    

  
  :type FaceIds: list
  :param FaceIds: 

    An array of face IDs to filter results with when listing faces in a collection.

    

  
    - *(string) --* 

    

  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'Faces': [
              {
                  'FaceId': 'string',
                  'BoundingBox': {
                      'Width': ...,
                      'Height': ...,
                      'Left': ...,
                      'Top': ...
                  },
                  'ImageId': 'string',
                  'ExternalImageId': 'string',
                  'Confidence': ...,
                  'IndexFacesModelVersion': 'string',
                  'UserId': 'string'
              },
          ],
          'NextToken': 'string',
          'FaceModelVersion': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **Faces** *(list) --* 

        An array of ``Face`` objects.

        
        

        - *(dict) --* 

          Describes the face properties such as the bounding box, face ID, image ID of the input image, and external image ID that you assigned.

          
          

          - **FaceId** *(string) --* 

            Unique identifier that Amazon Rekognition assigns to the face.

            
          

          - **BoundingBox** *(dict) --* 

            Bounding box of the face.

            
            

            - **Width** *(float) --* 

              Width of the bounding box as a ratio of the overall image width.

              
            

            - **Height** *(float) --* 

              Height of the bounding box as a ratio of the overall image height.

              
            

            - **Left** *(float) --* 

              Left coordinate of the bounding box as a ratio of overall image width.

              
            

            - **Top** *(float) --* 

              Top coordinate of the bounding box as a ratio of overall image height.

              
        
          

          - **ImageId** *(string) --* 

            Unique identifier that Amazon Rekognition assigns to the input image.

            
          

          - **ExternalImageId** *(string) --* 

            Identifier that you assign to all the faces in the input image.

            
          

          - **Confidence** *(float) --* 

            Confidence level that the bounding box contains a face (and not a different object such as a tree).

            
          

          - **IndexFacesModelVersion** *(string) --* 

            The version of the face detect and storage model that was used when indexing the face vector.

            
          

          - **UserId** *(string) --* 

            Unique identifier assigned to the user.

            
      
    
      

      - **NextToken** *(string) --* 

        If the response is truncated, Amazon Rekognition returns this token that you can use in the subsequent request to retrieve the next set of faces.

        
      

      - **FaceModelVersion** *(string) --* 

        Version number of the face detection model associated with the input collection ( ``CollectionId``).

        
  
  **Exceptions**
  
  *   :py:class:`Rekognition.Client.exceptions.InvalidParameterException`

  
  *   :py:class:`Rekognition.Client.exceptions.AccessDeniedException`

  
  *   :py:class:`Rekognition.Client.exceptions.InternalServerError`

  
  *   :py:class:`Rekognition.Client.exceptions.ThrottlingException`

  
  *   :py:class:`Rekognition.Client.exceptions.ProvisionedThroughputExceededException`

  
  *   :py:class:`Rekognition.Client.exceptions.InvalidPaginationTokenException`

  
  *   :py:class:`Rekognition.Client.exceptions.ResourceNotFoundException`

  

  **Examples**

  This operation lists the faces in a Rekognition collection.
  ::

    response = client.list_faces(
        CollectionId='myphotos',
        MaxResults=20,
    )
    
    print(response)

  
  Expected Output:
  ::

    {
        'Faces': [
            {
                'BoundingBox': {
                    'Height': 0.18000000715255737,
                    'Left': 0.5555559992790222,
                    'Top': 0.336667001247406,
                    'Width': 0.23999999463558197,
                },
                'Confidence': 100,
                'FaceId': '1c62e8b5-69a7-5b7d-b3cd-db4338a8a7e7',
                'ImageId': '147fdf82-7a71-52cf-819b-e786c7b9746e',
            },
            {
                'BoundingBox': {
                    'Height': 0.16555599868297577,
                    'Left': 0.30963000655174255,
                    'Top': 0.7066670060157776,
                    'Width': 0.22074100375175476,
                },
                'Confidence': 100,
                'FaceId': '29a75abe-397b-5101-ba4f-706783b2246c',
                'ImageId': '147fdf82-7a71-52cf-819b-e786c7b9746e',
            },
            {
                'BoundingBox': {
                    'Height': 0.3234420120716095,
                    'Left': 0.3233329951763153,
                    'Top': 0.5,
                    'Width': 0.24222199618816376,
                },
                'Confidence': 99.99829864501953,
                'FaceId': '38271d79-7bc2-5efb-b752-398a8d575b85',
                'ImageId': 'd5631190-d039-54e4-b267-abd22c8647c5',
            },
            {
                'BoundingBox': {
                    'Height': 0.03555560111999512,
                    'Left': 0.37388700246810913,
                    'Top': 0.2477779984474182,
                    'Width': 0.04747769981622696,
                },
                'Confidence': 99.99210357666016,
                'FaceId': '3b01bef0-c883-5654-ba42-d5ad28b720b3',
                'ImageId': '812d9f04-86f9-54fc-9275-8d0dcbcb6784',
            },
            {
                'BoundingBox': {
                    'Height': 0.05333330109715462,
                    'Left': 0.2937690019607544,
                    'Top': 0.35666701197624207,
                    'Width': 0.07121659815311432,
                },
                'Confidence': 99.99919891357422,
                'FaceId': '4839a608-49d0-566c-8301-509d71b534d1',
                'ImageId': '812d9f04-86f9-54fc-9275-8d0dcbcb6784',
            },
            {
                'BoundingBox': {
                    'Height': 0.3249259889125824,
                    'Left': 0.5155559778213501,
                    'Top': 0.1513350009918213,
                    'Width': 0.24333299696445465,
                },
                'Confidence': 99.99949645996094,
                'FaceId': '70008e50-75e4-55d0-8e80-363fb73b3a14',
                'ImageId': 'd5631190-d039-54e4-b267-abd22c8647c5',
            },
            {
                'BoundingBox': {
                    'Height': 0.03777780011296272,
                    'Left': 0.7002969980239868,
                    'Top': 0.18777799606323242,
                    'Width': 0.05044509842991829,
                },
                'Confidence': 99.92639923095703,
                'FaceId': '7f5f88ed-d684-5a88-b0df-01e4a521552b',
                'ImageId': '812d9f04-86f9-54fc-9275-8d0dcbcb6784',
            },
            {
                'BoundingBox': {
                    'Height': 0.05555560067296028,
                    'Left': 0.13946600258350372,
                    'Top': 0.46333301067352295,
                    'Width': 0.07270029932260513,
                },
                'Confidence': 99.99469757080078,
                'FaceId': '895b4e2c-81de-5902-a4bd-d1792bda00b2',
                'ImageId': '812d9f04-86f9-54fc-9275-8d0dcbcb6784',
            },
            {
                'BoundingBox': {
                    'Height': 0.3259260058403015,
                    'Left': 0.5144439935684204,
                    'Top': 0.15111100673675537,
                    'Width': 0.24444399774074554,
                },
                'Confidence': 99.99949645996094,
                'FaceId': '8be04dba-4e58-520d-850e-9eae4af70eb2',
                'ImageId': '465f4e93-763e-51d0-b030-b9667a2d94b1',
            },
            {
                'BoundingBox': {
                    'Height': 0.18888899683952332,
                    'Left': 0.3783380091190338,
                    'Top': 0.2355560064315796,
                    'Width': 0.25222599506378174,
                },
                'Confidence': 99.9999008178711,
                'FaceId': '908544ad-edc3-59df-8faf-6a87cc256cf5',
                'ImageId': '3c731605-d772-541a-a5e7-0375dbc68a07',
            },
            {
                'BoundingBox': {
                    'Height': 0.33481499552726746,
                    'Left': 0.31888899207115173,
                    'Top': 0.49333301186561584,
                    'Width': 0.25,
                },
                'Confidence': 99.99909973144531,
                'FaceId': 'ff43d742-0c13-5d16-a3e8-03d3f58e980b',
                'ImageId': '465f4e93-763e-51d0-b030-b9667a2d94b1',
            },
        ],
        'ResponseMetadata': {
            '...': '...',
        },
    }

  