ListFacesCommand

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.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { RekognitionClient, ListFacesCommand } from "@aws-sdk/client-rekognition"; // ES Modules import
// const { RekognitionClient, ListFacesCommand } = require("@aws-sdk/client-rekognition"); // CommonJS import
const client = new RekognitionClient(config);
const input = { // ListFacesRequest
  CollectionId: "STRING_VALUE", // required
  NextToken: "STRING_VALUE",
  MaxResults: Number("int"),
  UserId: "STRING_VALUE",
  FaceIds: [ // FaceIdList
    "STRING_VALUE",
  ],
};
const command = new ListFacesCommand(input);
const response = await client.send(command);
// { // ListFacesResponse
//   Faces: [ // FaceList
//     { // Face
//       FaceId: "STRING_VALUE",
//       BoundingBox: { // BoundingBox
//         Width: Number("float"),
//         Height: Number("float"),
//         Left: Number("float"),
//         Top: Number("float"),
//       },
//       ImageId: "STRING_VALUE",
//       ExternalImageId: "STRING_VALUE",
//       Confidence: Number("float"),
//       IndexFacesModelVersion: "STRING_VALUE",
//       UserId: "STRING_VALUE",
//     },
//   ],
//   NextToken: "STRING_VALUE",
//   FaceModelVersion: "STRING_VALUE",
// };

Example Usage

 Loading code editor

ListFacesCommand Input

See ListFacesCommandInput for more details

Parameter
Type
Description
CollectionId
Required
string | undefined

ID of the collection from which to list the faces.

FaceIds
string[] | undefined

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

MaxResults
number | undefined

Maximum number of faces to return.

NextToken
string | undefined

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.

UserId
string | undefined

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

ListFacesCommand Output

See ListFacesCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
FaceModelVersion
string | undefined

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

Faces
Face[] | undefined

An array of Face objects.

NextToken
string | undefined

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.

Throws

Name
Fault
Details
AccessDeniedException
client

You are not authorized to perform the action.

InternalServerError
server

Amazon Rekognition experienced a service issue. Try your call again.

InvalidPaginationTokenException
client

Pagination token in the request is not valid.

InvalidParameterException
client

Input parameter violated a constraint. Validate your parameter before calling the API operation again.

ProvisionedThroughputExceededException
client

The number of requests exceeded your throughput limit. If you want to increase this limit, contact Amazon Rekognition.

ResourceNotFoundException
client

The resource specified in the request cannot be found.

ThrottlingException
server

Amazon Rekognition is temporarily unable to process the request. Try your call again.

RekognitionServiceException
Base exception class for all service exceptions from Rekognition service.