# ListFaces

Returns a list of faces in a specified database. The action can also return information about the images and metadata associated with each face.

Type: synchronous

Parameter | Description | Required
--- | --- | ---
`database` | The name of the database that contains the faces. | Yes
`identifier` | A comma-separated list of identifiers to specify the faces to list. If you do not set this parameter, Media Server lists all of the faces in the specified database. | No
`imagestatus` | A Boolean value (default false) that specifies whether to return the label and training status of each image associated with each face. | No
`maxresults` | The maximum number of faces to return. | No
`metadata` | A Boolean value (default false) that specifies whether to return the metadata associated with each face. | No
`start` | The starting point for the list when you set the `maxresults` parameter. For example, to start listing faces from the tenth face in the database, set `start=10`. The entries in the database are indexed from 1. | No

## Example

The following example lists up to 10 faces contained in the `politicians` database. The response includes the label and training status of each training image, and any metadata associated with each face:

    /action=ListFaces&database=politicians
                     &imagestatus=TRUE
                     &metadata=TRUE
                     &start=1
                     &maxresults=10

## Response

The response always includes the following information for each face:

- `identifier` - The identifier for the face.
- `numimages` - The number of training images associated with the face.
- `numtrained` - The number of images associated with the face that have been trained (the number that are used for recognition).
- `numfailed` - The number of images associated with the face where training failed (for example, those images where Media Server could not detect a face and therefore cannot use the image for face recognition).
- `numuntrained` - The number of images associated with the face that have not yet been trained.

If you set the action parameter `imagestatus` to `true`, Media Server returns the status of each training image associated with each face.

- The `status` element indicates the status of training:

  - `trained` indicates that training was successful.
  - `untrained` indicates that training has not been attempted. Run training for the face using the action BuildFace, or run training for all faces that have incomplete training using the action BuildAllFaces.
  - `failed` indicates that Media Server could not use the image for training. For example, if Media Server does not detect a face in an image, it cannot be used as a training image. Remove the failed image using the action RemoveFaceImages.
- The `hasimagedata` element indicates whether the training image is stored in the database. If the value of this element is `false`, the image has been removed from the database by the action NullFaceImageData. Images that have been removed and have a status of `untrained` cannot be trained, so Micro Focus recommends you remove these images with the action RemoveFaceImages.

    <autnresponse>
      <action>LISTFACES</action>
      <response>SUCCESS</response>
      <responsedata>
        <entry>
          <identifier>JohnSmith</identifier>
          <numimages>3</numimages>
          <numtrained>2</numtrained>
          <numfailed>0</numfailed>
          <numuntrained>1</numuntrained>
          <images>
            <image>
              <label>image1</label>
              <status>trained</status>
              <hasimagedata>true</hasimagedata>
            </image>
            <image>
              <label>image2</label>
              <status>trained</status>
              <hasimagedata>true</hasimagedata>
            </image>
            <image>
              <label>image2</label>
              <status>untrained</status>
              <hasimagedata>true</hasimagedata>
            </image>
          </images>
          <metadata>
            <item>
              <key>firstname</key>
              <value>John</value>
            </item>
            <item>
              <key>lastname</key>
              <value>Smith</value>
            </item>
          </metadata>
        </entry>
      </responsedata>
    </autnresponse>

_FT_HTML5_bannerTitle.htm