Sign in

v1

latestOpenAPI 3.0.0Apache 2.0 License2026-07-1465453454.1 KB

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.

post/#X-Amz-Target=RekognitionService.ListFaces

Query parameters

MaxResultsstring

Pagination limit

NextTokenstring

Pagination token

Headers

X-Amz-Target'RekognitionService.ListFaces' required

Request body

CollectionIdstring required

ID of the collection from which to list the faces.

NextTokenstring

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.

MaxResultsinteger

Maximum number of faces to return.

Response

Success

NextTokenstring

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.

FaceModelVersionstring

Version number of the face detection model associated with the input collection (<code>CollectionId</code>).

Example response

{
  "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"
    }
  ]
}