Media Server 25.3
Media Server Help

# 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 OpenText 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>

Copyright 2025 Open Text
Version 25.3 | Last updated July 2025

Send documentation feedback

Close

Send documentation feedback

To send feedback using your default email client, open an email window.

Otherwise, send your feedback and the information below to MFI-swpdl.idoldocsfeedback@opentext.com.

We appreciate your feedback!

Product: Knowledge Discovery Media Server 25.3

Topic Title: ListFaces