# GetFaceDetection


Gets face detection results for a Amazon Rekognition Video analysis started by [StartFaceDetection](API_StartFaceDetection.md).

Face detection with Amazon Rekognition Video is an asynchronous operation. You start face detection by calling [StartFaceDetection](API_StartFaceDetection.md) which returns a job identifier (`JobId`). When the face detection operation finishes, Amazon Rekognition Video publishes a completion status to the Amazon Simple Notification Service topic registered in the initial call to `StartFaceDetection`. To get the results of the face detection operation, first check that the status value published to the Amazon SNS topic is `SUCCEEDED`. If so, call [GetFaceDetection](#API_GetFaceDetection) and pass the job identifier (`JobId`) from the initial call to `StartFaceDetection`.

 `GetFaceDetection` returns an array of detected faces (`Faces`) sorted by the time the faces were detected. 

Use MaxResults parameter to limit the number of labels returned. If there are more results than specified in `MaxResults`, the value of `NextToken` in the operation response contains a pagination token for getting the next set of results. To get the next page of results, call `GetFaceDetection` and populate the `NextToken` request parameter with the token value returned from the previous call to `GetFaceDetection`.

Note that for the `GetFaceDetection` operation, the returned values for `FaceOccluded` and `EyeDirection` will always be "null".

## Request Syntax


```
{
   "JobId": "string",
   "MaxResults": number,
   "NextToken": "string"
}
```

## Request Parameters


For information about the parameters that are common to all actions, see [Common Parameters](CommonParameters.md).

The request accepts the following data in JSON format.

 ** [JobId](#API_GetFaceDetection_RequestSyntax) **   <a name="rekognition-GetFaceDetection-request-JobId"></a>
Unique identifier for the face detection job. The `JobId` is returned from `StartFaceDetection`.  
Type: String  
Length Constraints: Minimum length of 1. Maximum length of 64.  
Pattern: `^[a-zA-Z0-9-_]+$`   
Required: Yes

 ** [MaxResults](#API_GetFaceDetection_RequestSyntax) **   <a name="rekognition-GetFaceDetection-request-MaxResults"></a>
Maximum number of results to return per paginated call. The largest value you can specify is 1000. If you specify a value greater than 1000, a maximum of 1000 results is returned. The default value is 1000.  
Type: Integer  
Valid Range: Minimum value of 1.  
Required: No

 ** [NextToken](#API_GetFaceDetection_RequestSyntax) **   <a name="rekognition-GetFaceDetection-request-NextToken"></a>
If the previous response was incomplete (because there are more faces to retrieve), Amazon Rekognition Video returns a pagination token in the response. You can use this pagination token to retrieve the next set of faces.  
Type: String  
Length Constraints: Maximum length of 255.  
Required: No

## Response Syntax


```
{
   "Faces": [ 
      { 
         "Face": { 
            "AgeRange": { 
               "High": number,
               "Low": number
            },
            "Beard": { 
               "Confidence": number,
               "Value": boolean
            },
            "BoundingBox": { 
               "Height": number,
               "Left": number,
               "Top": number,
               "Width": number
            },
            "Confidence": number,
            "Emotions": [ 
               { 
                  "Confidence": number,
                  "Type": "string"
               }
            ],
            "EyeDirection": { 
               "Confidence": number,
               "Pitch": number,
               "Yaw": number
            },
            "Eyeglasses": { 
               "Confidence": number,
               "Value": boolean
            },
            "EyesOpen": { 
               "Confidence": number,
               "Value": boolean
            },
            "FaceOccluded": { 
               "Confidence": number,
               "Value": boolean
            },
            "Gender": { 
               "Confidence": number,
               "Value": "string"
            },
            "Landmarks": [ 
               { 
                  "Type": "string",
                  "X": number,
                  "Y": number
               }
            ],
            "MouthOpen": { 
               "Confidence": number,
               "Value": boolean
            },
            "Mustache": { 
               "Confidence": number,
               "Value": boolean
            },
            "Pose": { 
               "Pitch": number,
               "Roll": number,
               "Yaw": number
            },
            "Quality": { 
               "Brightness": number,
               "Sharpness": number
            },
            "Smile": { 
               "Confidence": number,
               "Value": boolean
            },
            "Sunglasses": { 
               "Confidence": number,
               "Value": boolean
            }
         },
         "Timestamp": number
      }
   ],
   "JobId": "string",
   "JobStatus": "string",
   "JobTag": "string",
   "NextToken": "string",
   "StatusMessage": "string",
   "Video": { 
      "S3Object": { 
         "Bucket": "string",
         "Name": "string",
         "Version": "string"
      }
   },
   "VideoMetadata": { 
      "Codec": "string",
      "ColorRange": "string",
      "DurationMillis": number,
      "Format": "string",
      "FrameHeight": number,
      "FrameRate": number,
      "FrameWidth": number
   }
}
```

## Response Elements


If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

 ** [Faces](#API_GetFaceDetection_ResponseSyntax) **   <a name="rekognition-GetFaceDetection-response-Faces"></a>
An array of faces detected in the video. Each element contains a detected face's details and the time, in milliseconds from the start of the video, the face was detected.   
Type: Array of [FaceDetection](API_FaceDetection.md) objects

 ** [JobId](#API_GetFaceDetection_ResponseSyntax) **   <a name="rekognition-GetFaceDetection-response-JobId"></a>
Job identifier for the face detection operation for which you want to obtain results. The job identifer is returned by an initial call to StartFaceDetection.  
Type: String  
Length Constraints: Minimum length of 1. Maximum length of 64.  
Pattern: `^[a-zA-Z0-9-_]+$` 

 ** [JobStatus](#API_GetFaceDetection_ResponseSyntax) **   <a name="rekognition-GetFaceDetection-response-JobStatus"></a>
The current status of the face detection job.  
Type: String  
Valid Values: `IN_PROGRESS | SUCCEEDED | FAILED` 

 ** [JobTag](#API_GetFaceDetection_ResponseSyntax) **   <a name="rekognition-GetFaceDetection-response-JobTag"></a>
A job identifier specified in the call to StartFaceDetection and returned in the job completion notification sent to your Amazon Simple Notification Service topic.  
Type: String  
Length Constraints: Minimum length of 1. Maximum length of 1024.  
Pattern: `[a-zA-Z0-9_.\-:+=\/]+` 

 ** [NextToken](#API_GetFaceDetection_ResponseSyntax) **   <a name="rekognition-GetFaceDetection-response-NextToken"></a>
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.   
Type: String  
Length Constraints: Maximum length of 255.

 ** [StatusMessage](#API_GetFaceDetection_ResponseSyntax) **   <a name="rekognition-GetFaceDetection-response-StatusMessage"></a>
If the job fails, `StatusMessage` provides a descriptive error message.  
Type: String

 ** [Video](#API_GetFaceDetection_ResponseSyntax) **   <a name="rekognition-GetFaceDetection-response-Video"></a>
Video file stored in an Amazon S3 bucket. Amazon Rekognition video start operations such as [StartLabelDetection](API_StartLabelDetection.md) use `Video` to specify a video for analysis. The supported file formats are .mp4, .mov and .avi.  
Type: [Video](API_Video.md) object

 ** [VideoMetadata](#API_GetFaceDetection_ResponseSyntax) **   <a name="rekognition-GetFaceDetection-response-VideoMetadata"></a>
Information about a video that Amazon Rekognition Video analyzed. `Videometadata` is returned in every page of paginated responses from a Amazon Rekognition video operation.  
Type: [VideoMetadata](API_VideoMetadata.md) object

## Errors


For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md).

 ** AccessDeniedException **   
You are not authorized to perform the action.  
HTTP Status Code: 400

 ** InternalServerError **   
Amazon Rekognition experienced a service issue. Try your call again.  
HTTP Status Code: 500

 ** InvalidPaginationTokenException **   
Pagination token in the request is not valid.  
HTTP Status Code: 400

 ** InvalidParameterException **   
Input parameter violated a constraint. Validate your parameter before calling the API operation again.  
HTTP Status Code: 400

 ** ProvisionedThroughputExceededException **   
The number of requests exceeded your throughput limit. If you want to increase this limit, contact Amazon Rekognition.  
HTTP Status Code: 400

 ** ResourceNotFoundException **   
The resource specified in the request cannot be found.  
HTTP Status Code: 400

 ** ThrottlingException **   
Amazon Rekognition is temporarily unable to process the request. Try your call again.  
HTTP Status Code: 500

## See Also


For more information about using this API in one of the language-specific AWS SDKs, see the following:
+  [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/rekognition-2016-06-27/GetFaceDetection) 
+  [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/rekognition-2016-06-27/GetFaceDetection) 
+  [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/rekognition-2016-06-27/GetFaceDetection) 
+  [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/rekognition-2016-06-27/GetFaceDetection) 
+  [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/rekognition-2016-06-27/GetFaceDetection) 
+  [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/rekognition-2016-06-27/GetFaceDetection) 
+  [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/rekognition-2016-06-27/GetFaceDetection) 
+  [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/rekognition-2016-06-27/GetFaceDetection) 
+  [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/rekognition-2016-06-27/GetFaceDetection) 
+  [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/rekognition-2016-06-27/GetFaceDetection)