> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 컬렉션의 얼굴 목록 가져오기

> 특정 컬렉션 내에 포함된 모든 얼굴의 목록을 검색

이 API 엔드포인트를 통해 특정 컬렉션 내에 포함된 모든 얼굴의 목록을 검색할 수 있습니다. 페이지네이션 및 검색 기능을 사용하여 대용량 얼굴 데이터 컬렉션을 효율적으로 관리할 수 있습니다.

## 요청

### 헤더

<ParamField header="x-api-key" type="string">
  인증 및 접근 제어에 사용되는 API 키입니다. 이 헤더 매개변수는 인증에 필요합니다.
</ParamField>

### 쿼리 매개변수

<ParamField header="collectionId" type="string" required>
  얼굴이 추가될 컬렉션의 고유 식별자입니다.
</ParamField>

<ParamField header="page" type="string" required>
  페이지네이션을 위한 페이지 번호입니다. 반복당 50개의 데이터를 반환합니다.
</ParamField>

<ParamField header="term" type="string">
  특정 문자열을 포함하는 faceIds 목록을 검색합니다. (최소 5자 이상이어야 함)
</ParamField>

## 응답

### 성공 응답 (200)

<ResponseField name="message" type="string">
  결과를 나타내는 성공 또는 오류 메시지
</ResponseField>

<ResponseField name="result" type="array">
  다음을 포함하는 얼굴 객체의 배열:

  **collection\_id**: 얼굴 컬렉션의 고유 식별자

  **face\_id**: 컬렉션 내 얼굴의 고유 식별자

  **user\_name**: 얼굴과 관련된 사용자의 이름

  **create\_time**: 얼굴이 추가된 타임스탬프

  **meta\_face\_id**: 얼굴의 메타데이터 식별자
</ResponseField>

<ResponseField name="totalCount" type="string">
  검색 조건과 일치하는 총 얼굴 수를 나타냅니다. 이 예에서는 하나의 얼굴만 발견되었지만, 더 많은 일치 항목이 감지되면 이 값이 더 높을 수 있습니다.
</ResponseField>

### 오류 응답

#### 잘못된 요청 (400)

<ResponseField name="errorCode" type="number">
  문제 해결을 위한 특정 오류를 식별합니다:

  * 6024: CollectionId가 필요합니다
  * 6025: Term 문자열이 5자 미만입니다
  * 6026: Page가 누락되었습니다
  * 6027: 컬렉션 정보가 존재하지 않습니다
  * 6028: 이 컬렉션은 사용할 수 없습니다
  * 6029: 얼굴 목록 가져오기 실패
</ResponseField>

<ResponseField name="message" type="string">
  오류에 대한 간략한 설명입니다. 자세한 내용은 오류 코드를 참조하세요.
</ResponseField>

#### 금지됨 (403)

<ResponseField name="errorCode" type="number">
  문제 해결을 위한 특정 오류를 식별합니다:

  * 6039: API 키가 필요합니다
  * 6040: 액세스 거부: API 키를 사용할 수 없습니다
</ResponseField>

<ResponseField name="message" type="string">
  오류에 대한 간략한 설명입니다. 자세한 내용은 오류 코드를 참조하세요.
</ResponseField>


## OpenAPI

````yaml GET /faces
openapi: 3.1.0
info:
  title: Face ID API
  description: >-
    API for facial recognition and identity verification using Face ID
    technology
  version: 1.0.0
servers:
  - url: https://face.argosidentity.com
    description: Production server
security: []
paths:
  /faces:
    get:
      tags:
        - Face ID
      summary: Get list of faces in collection
      description: Retrieve a list of all faces contained within a specific collection
      operationId: getFaces
      parameters:
        - name: collectionId
          in: query
          required: true
          schema:
            type: string
          description: Unique identifier of the collection
        - name: page
          in: query
          required: true
          schema:
            type: string
          description: Page number for pagination. Returns 50 pieces of data per iteration
        - name: term
          in: query
          required: false
          schema:
            type: string
          description: >-
            Retrieves a list of faceIds containing a specific string. (Must be
            at least 5 characters long)
      responses:
        '200':
          description: List of faces retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Success message
                    example: Faces retrieved successfully
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        collection_id:
                          type: string
                          description: Unique identifier of the face collection
                        face_id:
                          type: string
                          description: Unique identifier for the face in the collection
                        user_name:
                          type: string
                          description: Name of the user associated with the face
                        create_time:
                          type: string
                          description: Timestamp when the face was added
                        meta_face_id:
                          type: string
                          description: A metadata identifier for the face
                  totalCount:
                    type: string
                    description: Total number of faces found that match the search criteria
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: number
                    description: Error code
                    enum:
                      - 6024
                      - 6025
                      - 6026
                      - 6027
                      - 6028
                      - 6029
                  message:
                    type: string
                    description: Error message
        '403':
          description: Forbidden - Authentication required
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: number
                    description: Error code
                    enum:
                      - 6039
                      - 6040
                  message:
                    type: string
                    description: Error message
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````