Get people list

Prev Next

Available in VPC

Get the people list.

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 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 List of person tag IDs to search
  • Multiple ID entries separated by , are supported.

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 Required API processing result code
message String Required API processing result message
result Object Required People list query result

result

The following describes the result item.

Field Type Required Description
content Array Required People list
totalCount Integer Required Total people count
totalPage Integer Required Total number of pages
pageNo Integer Required Current page number
pageSize Integer Required Number of items per page

result.content

The following describes the result.content item.

Field Type Required Description
id Integer Required Person ID
name String Required Person name
description String Optional Person description
tagNames Array Required Person tag name list
  • 0-N
thumbnailId Integer Optional Main thumbnail ID
thumbnailUrl String Optional Main thumbnail image URL
  • Presigned URL
updatedTime String Required Last modification date and time of person information
  • ISO 8601 format
updatedUserName String Required User name who last edited the person information

Response status codes

For information about the HTTP 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,
        "name": "Gildong Hong",
        "description": "A representative fictional character in Korea.",
        "tagNames": ["Singer", "Actor"],
        "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
  }
}