- Navigation GuideYou are on a Command (operation) page with structural examples. Use the navigation breadcrumb if you would like to return to the Client landing page.
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
ListFacesCommand Input
Parameter | Type | Description |
---|
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
Parameter | Type | Description |
---|
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 ( |
Faces | Face[] | undefined | An array of |
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 |
---|
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. |