Getting information about subjects in the Yandex Cloud access management system

Written by

Updated at November 12, 2026

Getting a list of subjects
- Examples
Getting attributes of individual subjects
- Examples

Yandex Identity and Access Management provides a feature for getting information about subjects to search for and retrieve attributes of different types of subjects in the Yandex Cloud access management system within your organization.

Roles required to get information about subjects depend on the target subject type:

Users: organization-manager.users.viewer role or higher for the organization.
Service accounts: iam.auditor role or higher for the organization.
User groups, system groups, and public groups: organization-manager.groups.viewer role or higher for the organization.
Yandex account users who have been invited to the organization but have not yet accepted the invitation: organization-manager.users.viewer role or higher for the organization.

Getting a list of subjects

To get a list of subjects in an organization:

CLI

API

If you do not have the Yandex Cloud CLI yet, install and initialize it.

See the description of the CLI command for getting a list of subjects in an organization:
```
yc iam subject-details list --help
```

Get a list of available organizations:

yc organization-manager organization list

Result:

+----------------------+-----------------------------+-------------------------+--------+
|          ID          |            NAME             |          TITLE          | LABELS |
+----------------------+-----------------------------+-------------------------+--------+
| bpf1smsil5q0******** | org1-technical-name         | Organization One        |        |
| bpf2c65rqcl8******** | org2-technical-name         | Organization Two        |        |
| bpfaidqca8vd******** | org3-technical-name         | Organization Three      |        |
+----------------------+-----------------------------+-------------------------+--------+

Copy the organization ID from the ID field.

Get your list of subjects:
```
yc iam subject-details list \
  --organization-id <organization_ID> \
  --field-mask <attribute_list> \
  --filter '(<filtering_CEL_expression>)' \
  --limit <number_of_subjects> \
  --format yaml
```
Where:
- --organization-id: ID of the organization whose list of subjects you want to get.
- --field-mask: Mask of subjects, i.e., a list of attributes you want to get. Available attributes are subject type-specific.
  
  For example, to display a list of creation dates, email addresses, and last names of your users, set this parameter to created_at,user_account.email,user_account.family_name.
  
  This is an optional setting. By default, regardless of the --field-mask parameter value, the list shows subject IDs and types.
- --filter: Filtering expression in Common Expression Language (CEL).
  
  For example, to display only a list of local users whose profiles have the Email field filled in and whose email address contains ivan, set this parameter to the following:
```
'(subject.type in [1] && 
has(subject.user_account.email) && 
subject.user_account.email.icontains("ivan"))'
```
  Note
  
  For case-insensitive substring matching, use the icontains function.
  
  This is an optional setting. By default, no filters apply to the results.
- --limit: Limits the number of subjects in the result list. This is an optional setting. The default value is 1000.
- --format: To get results with attributes other than the default values, use the json or yaml output format.
Result:
```
- sub: ek09f4kjk3mk********
  type: USER_ACCOUNT
  created_at: "2026-09-23T16:54:03.297124Z"
  user_account:
    family_name: Ivanov
    email: Sergey-Ivanov@example.com
- sub: ek0ogbhh6o3p********
  type: USER_ACCOUNT
  created_at: "2026-09-23T16:55:42.318668Z"
  user_account:
    family_name: Sergeev
    email: IVANsergeev@example.com
```

Use the list REST API method for the SubjectDetails resource or the SubjectDetailsService/List gRPC API call.

To get specific attributes of the subjects, provide them in the field_mask field. To filter the results as needed, provide a filtering expression in Common Expression Language (CEL) to the filter field. For more information, see Getting information about subjects in the Yandex Cloud access management system.

Examples

Getting a list of all subjects created after a specific date

CLI

Run this command:

yc iam subject-details list \
  --organization-id bpf2c65rqcl8******** \
  --field-mask created_at \
  --filter '(subject.created_at >= timestamp("2026-09-01T00:00:00Z"))' \
  --format yaml

Result

- sub: aje7gcq7usen********
  type: SERVICE_ACCOUNT
  created_at: "2026-09-24T07:26:05.813707Z"
- sub: ek09f4kjk3mk********
  type: USER_ACCOUNT
  created_at: "2026-09-23T16:54:03.297124Z"
- sub: ek0ogbhh6o3p********
  type: USER_ACCOUNT
  created_at: "2026-09-23T16:55:42.318668Z"

Getting a list of names of service accounts residing in specific folders

CLI

Run this command:

yc iam subject-details list \
  --organization-id bpf2c65rqcl8******** \
  --field-mask name,service_account.folder.id \
  --filter '(subject.service_account.folder.id in ["b1gkd6dks6i1********", "b1gfq9pe6rd2********"])' \
  --format yaml

Result

- sub: aje8ibek25c6********
  type: SERVICE_ACCOUNT
  name: sa-sd
  service_account:
    folder:
      id: b1gkd6dks6i1********
- sub: ajepodjpcifj********
  type: SERVICE_ACCOUNT
  name: sa-lockbox
  service_account:
    folder:
      id: b1gfq9pe6rd2********
- sub: ajet9uglmjir********
  type: SERVICE_ACCOUNT
  name: sample-sa
  service_account:
    folder:
      id: b1gkd6dks6i1********

Getting a list of statuses for local users without a phone number

CLI

Run this command:

yc iam subject-details list \
  --organization-id bpf2c65rqcl8******** \
  --field-mask status \
  --filter '(subject.user_account.subject_container.container_type == 4 && 
            !has(subject.user_account.phone_number))' \
  --format yaml

Result

- sub: aje3i1gq49n3********
  type: USER_ACCOUNT
  status: ACTIVE
- sub: ajejij9f440p********
  type: USER_ACCOUNT
  status: ACTIVE
- sub: ajejvne736i3********
  type: USER_ACCOUNT
  status: ACTIVE
- sub: ek09f4kjk3mk********
  type: USER_ACCOUNT
  status: SUSPENDED

Getting attributes of individual subjects

To get attributes of individual subjects in an organization:

CLI

API

If you do not have the Yandex Cloud CLI yet, install and initialize it.

See the description of the CLI command for getting attributes of individual subjects in an organization:
```
yc iam subject-details get --help
```
Get information about your subjects:
```
yc iam subject-details get \
  --subject-ids <list_of_IDs> \
  --field-mask <attribute_list> \
  --filter '(<filtering_CEL_expression>)' \
  --format yaml \
  --organization-id <organization_ID>
```
Where:
- --subject-ids: List of IDs of subjects whose attributes you want to get. comma-separated. Here is an example: ek09f4kjk3mk********,ek0ogbhh6o3p********.
- --field-mask: Mask of subjects, i.e., a list of attributes you want to get. Available attributes are subject type-specific.
  
  For example, to get email addresses and complete employment information for users, set this parameter to user_account.email,user_account.job_info.
  
  This is an optional setting. By default, regardless of the --field-mask parameter value, the list shows subject IDs and types.
- --filter: Filtering expression in Common Expression Language (CEL).
  
  For example, to make the command output only those users who have the fields under Organizational information filled in, set this parameter to the following:
```
'(has(subject.user_account.job_info))'
```
  This is an optional setting. By default, no filters apply to the results.
- --format: To get results with attributes other than the default values, use the json or yaml output format.
- --organization-id: ID of the organization the target subjects belong to.
  
  This is an optional setting. Specify the organization ID when it is impossible to get the information without it.
  
  Tip
  
  For example, the organization ID must be specified when trying to get a list of groups that a user with a Yandex account belongs to. You must specify the organization explicitly because such a user can belong to multiple different organizations at once.
Result:
```
- sub: ek09f4kjk3mk********
  type: USER_ACCOUNT
  user_account:
    email: Sergey-Ivanov@example.com
    job_info:
      company_name: Top Company
      department: Accounting
      job_title: Senior Accountant
      employee_id: "456"
- sub: ek0ogbhh6o3p********
  type: USER_ACCOUNT
  user_account:
    email: IVANsergeev@example.com
    job_info:
      company_name: Top Company
      department: IT
      job_title: DevOps engineer
      employee_id: "123"
```

Use the batchGet REST API method for the SubjectDetails resource or the SubjectDetailsService/BatchGet gRPC API call.

Examples

Getting a list of groups the user is a member of

CLI

Note

To get a list of groups for a user with a Yandex account, provide the organization ID in the command.

Run this command:

yc iam subject-details get \
  --subject-ids ajei280a73vc******** \
  --field-mask groups \
  --organization-id bpf2c65rqcl8******** \
  --format yaml

Result

sub: ajei280a73vc********
type: USER_ACCOUNT
groups:
  - id: ajeql2iqn9d1********
    name: sample-group
    type: EXPLICIT
  - id: allUsers
    name: All users
    type: PUBLIC_ACCESS
  - id: allAuthenticatedUsers
    name: All authenticated users
    type: PUBLIC_ACCESS
  - id: group:organization:bpf2c65rqcl8********:users
    name: All users in organization Test Organization
    type: META

Getting all available user attributes

CLI

Run this command:

yc iam subject-details get \
  --subject-ids aje3b3juqevc********,ek0ogbhh6o3p********,ajei280a73vc******** \
  --field-mask created_at,status,name,last_authenticated_at,external_id,user_account \
  --format yaml

Result

- sub: aje3b3juqevc********
  type: USER_ACCOUNT
  created_at: "2025-08-03T18:38:44.195748Z"
  status: ACTIVE
  user_account:
    preferred_username: sample-federated-user
    subject_container:
      id: bpfsuecgv39i********
      name: sample-federation
      container_type: SAML
    last_id_proof_at: "2025-08-03T18:38:44.195748Z"
    modified_at: "2025-08-03T18:38:44.195748Z"
  external_id: sample-federated-user
- sub: ek0ogbhh6o3p********
  type: USER_ACCOUNT
  created_at: "2026-09-23T16:55:42.318668Z"
  status: ACTIVE
  name: Ivan Sergeev
  user_account:
    given_name: Ivan
    family_name: Sergeev
    preferred_username: ivanserg@example.com
    email: IVANsergeev@example.com
    subject_container:
      id: ek0o6g0irskn********
      name: sample-pool
      container_type: USERPOOL
    job_info:
      company_name: Top Company
      department: IT
      job_title: DevOps engineer
      employee_id: "123"
    modified_at: "2026-09-23T19:48:49.112910Z"
- sub: ajei280a73vc********
  type: USER_ACCOUNT
  created_at: "2020-01-23T06:21:07Z"
  status: ACTIVE
  name: Aleksey I.
  last_authenticated_at: "2026-09-24T05:40:00Z"
  user_account:
    given_name: Aleksey
    family_name: Ivanov
    preferred_username: aivan********
    email: aivan********@yandex.ru
    phone_number: "+79876******"
    subject_container:
      id: yandex
      name: yandex
      container_type: PASSPORT
    last_id_proof_at: "2026-09-24T05:42:45.551123Z"
    modified_at: "2026-09-22T05:55:45.853516Z"
  external_id: "114*****"

Getting the last names of federated and local users who have never authenticated in Yandex Cloud

Warning

If your filter uses fields with the enum data type, provide the numeric values specified in the subject attributes table for such fields.

CLI

Run this command:

yc iam subject-details get \
  --subject-ids aje3b3juqevc********,ek0ogbhh6o3p********,ajei280a73vc******** \
  --field-mask user_account.family_name \
  --filter 'subject.user_account.subject_container.container_type in [1, 4] && 
            !has(subject.last_authenticated_at)' \
  --format yaml

Result

sub: ek0ogbhh6o3p********
type: USER_ACCOUNT
user_account:
  family_name: Sergeev

Useful links