---
title: "Search person"
slug: "mi-search-persons"
updated: 2026-10-08T04:13:16Z
published: 2026-10-08T04:13:16Z
canonical: "api.ncloud-docs.com/mi-search-persons"
---

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

# 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](/docs/en/maiu-list-persons) for simple list queries, and use the person search for searches with complex criteria and sorting.

- [Get person details](/docs/en/maiu-person-details): Get detailed information for 1 person.
- [Get people list](/docs/en/maiu-list-persons): 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](/docs/en/maiu-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94).

### 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](/docs/en/maiu-list-persons). |
| `tagIds` | Array[Integer] | Optional | Lists person tag IDs to search - Maximum 30. - See [Get person tag list](/docs/en/maiu-list-person-tags). |
| `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](/docs/en/maiu-overview#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C) |
| `message` | String | - | [API processing result message](/docs/en/maiu-overview#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C) |
| `result` | Object | - | Person search result |
| `result.content` | Array | - | People list: [content](/docs/en/mi-search-persons#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](/docs/en/mi-search-persons#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](/docs/en/maiu-overview#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C).

### 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
  }
}
```