Get people list

Available in VPC

Get the people list.

Note

To perform a search using complex criteria—such as selecting multiple person IDs, filtering by naming status, or specifying sort criteria—use Search person.

Request

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

Method	URI
GET	/api/v1/workspaces/{workspace_name}/persons

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 query parameters

You can use the following query parameters with your request:

Field	Type	Required	Description
`pageNum`	Integer	Required	Page number 1 or more
`pageSize`	Integer	Optional	Number of items per page 1-1000 (default: 1000)
`name`	String	Optional	Name of person to search 2-50 characters. Semicolons (`;`), vertical bars (`\\|`), and backticks (`) can't be used.
`tagIdList`	Array<Integer>	Optional	Lists person tag IDs to search. Supports multiple ID input separated by `,`. Up to 30 IDs.

Request example

The request example is as follows:

curl --location --request GET 'https://mi.apigw.ntruss.com/api/v1/workspaces/my-workspace/persons?pageNum=1&pageSize=10&name=홍길동&tagIdList=100,200' \
--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'

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	-	People list query result
`result.content`	Array	-	People list: content
`result.totalCount`	Integer	-	Total people count
`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
`tagNames`	Array	-	Person tag name list 0-N
`tags`	Array	-	List of tags set for a person: tags 0-N Use instead of `tagNames` when a tag ID is required.
`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.",
        "tagNames": ["Singer", "Actor"],
        "tags": [
          {
            "id": 201,
            "name": "Singer"
          },
          {
            "id": 202,
            "name": "Actor"
          }
        ],
        "assetCount": 12,
        "thumbnailId": 3001,
        "thumbnailUrl": "https://maiu.presigned.ncloudstorage.com/persons/thumbnails/hong.jpg?...",
        "updatedTime": "2025-08-15T17:13:48Z",
        "updatedUserName": "*dong Hong"
      }
    ],
    "totalCount": 2,
    "totalPage": 1,
    "pageNo": 1,
    "pageSize": 10
  }
}