Search person

Available in VPC

Search for people within a workspace using complex criteria such as name, ID, tags, and naming status. Passes the search criteria and sort criteria in the request body.

Note

The Get person API is categorized as follows depending on the use case. Use Get people list for simple list queries, and use the person search for searches with complex criteria and sorting.

Get person details: Get detailed information for 1 person.
Get people list: Get a simple list of people based on names and tags.
Search person: Perform complex searches, such as specifying multiple person IDs, filtering by naming status, and setting sort criteria.

Request

This section describes the request format. The method and URI are as follows:

Method	URI
POST	/api/v1/workspaces/{workspace_name}/persons/search

Request headers

For information about the request headers common to all Media Intelligence APIs, see Media Intelligence request headers.

Request path parameters

You can use the following path parameters with your request:

Field	Type	Required	Description
`workspace_name`	String	Required	Workspace name

Request body

You can include the following data in the body of your request:

Field	Type	Required	Description
`pageNum`	Integer	Required	Page number 1 or more
`pageSize`	Integer	Optional	Number of items per page 1-50 (default: 10)
`name`	String	Optional	Name of person to search 2-50 characters. Semicolons (`;`), vertical bars (`\\|`), and backticks (`) can't be used.
`personIds`	Array[Integer]	Optional	Lists person IDs to search Maximum 50. See Get people list.
`tagIds`	Array[Integer]	Optional	Lists person tag IDs to search Maximum 30. See Get person tag list.
`nameType`	String	Optional	Naming status of person `NAMED` \| `ANONYMOUS` `NAMED`: Person with a specified name. `ANONYMOUS`: Person without a specified name. If not entered, searches for all persons.
`sortColumn`	String	Optional	Sort criteria `ASSET_COUNT` (default) \| `CREATED_AT` \| `PERSON_ID` \| `NAME`
`sortType`	String	Optional	Sort direction `ASC` \| `DESC` (default)

Request example

The request example is as follows:

curl --location --request POST 'https://mi.apigw.ntruss.com/api/v1/workspaces/my-workspace/persons/search' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data '{
  "pageNum": 1,
  "pageSize": 10,
  "tagIds": [200],
  "nameType": "NAMED",
  "sortColumn": "ASSET_COUNT",
  "sortType": "DESC"
}'

Response

This section describes the response format.

Response body

The response body includes the following data:

Field	Type	Required	Description
`code`	String	-	API processing result code
`message`	String	-	API processing result message
`result`	Object	-	Person search result
`result.content`	Array	-	People list: content
`result.totalCount`	Integer	-	Total number of people matching the search criteria
`result.totalPage`	Integer	-	Total number of pages
`result.pageNo`	Integer	-	Current page number
`result.pageSize`	Integer	-	Number of items per page

`content`

The following describes content.

Field	Type	Required	Description
`id`	Integer	-	Person ID
`personId`	Integer	-	Person ID Value identical to `id`
`name`	String	-	Person name Anonymous persons are indicated as null.
`description`	String	-	Person description
`tags`	Array	-	List of tags set for the person: tags 0-N
`assetCount`	Integer	-	Number of assets featuring the person
`thumbnailId`	Integer	-	Main thumbnail ID
`thumbnailUrl`	String	-	Main thumbnail image URL Presigned URL
`updatedTime`	String	-	Last modification date and time of person information ISO 8601 format
`updatedUserName`	String	-	User name who last edited the person information

`tags`

The following describes tags.

Field	Type	Required	Description
`id`	Integer	-	Tag ID
`name`	String	-	Tag name

Response status codes

For information about the response status codes common to all Media Intelligence APIs, see Media Intelligence response status codes.

Response example

The response example is as follows:

{
  "code": "0",
  "message": "success",
  "result": {
    "content": [
      {
        "id": 1001,
        "personId": 1001,
        "name": "Gildong Hong",
        "description": "A representative fictional character in Korea.",
        "tags": [
          {
            "id": 200,
            "name": "Singer"
          }
        ],
        "assetCount": 12,
        "thumbnailId": 3001,
        "thumbnailUrl": "https://maiu.presigned.ncloudstorage.com/persons/thumbnails/hong.jpg?...",
        "updatedTime": "2026-09-01T17:13:48Z",
        "updatedUserName": "*dong Hong"
      }
    ],
    "totalCount": 1,
    "totalPage": 1,
    "pageNo": 1,
    "pageSize": 10
  }
}