Getting information about subjects in the Yandex Cloud access management system

Written by

Updated at November 12, 2026

Subject types
Available methods
- List
- BatchGet
Subject attributes
Subject filter

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

Additional flexibility when searching for subjects and retrieving subject attributes comes from using filters based on the Common Expression Language (CEL).

This feature is available in the Yandex Cloud CLI and API interfaces.

Subject types

You can use this feature to search for multiple subject types within an organization at the same time:

Subject type	Description	Minimum role required to get information
`USER_ACCOUNT`	Yandex account users, local users, and federated users	organization-manager.users.viewer or higher for the organization
`SERVICE_ACCOUNT`	Service accounts	iam.auditor or higher for the organization
`GROUP`	User groups, system groups, and public groups	organization-manager.groups.viewer or higher for the organization
`INVITEE`	Yandex account users who have been invited to the organization but have not yet accepted the invitation	organization-manager.users.viewer or higher for the organization

Available methods

Identity and Access Management supports two methods for getting information about subjects: List and BatchGet.

When calling either method, you can provide a subject mask (field-mask) that specifies which subject attributes to retrieve. If you do not specify a subject mask, the method only returns sub and type by default. The available attributes depend on the subject type. For more information, see Subject attributes.

You can also use a flexible CEL filter when calling either method to narrow down the list of subjects you want to get information about.

For more info on using methods for getting subject details, see Getting information about subjects in the Yandex Cloud access management system.

List

The List method returns a list of organization subjects and their details based on the organization ID. You can use the REST API, gRPC API, or yc iam subject-details list CLI command to call List.

When calling the List method, make sure to provide the ID of the organization to search for subjects in.

BatchGet

The BatchGet method returns information about specified organization subjects based on their IDs. You can use the REST API, gRPC API, or yc iam subject-details get CLI command to call BatchGet.

When calling the BatchGet method, you must specify at least one subject ID you want to get information about.

To get a list of groups that include a Yandex account user, make sure to provide the organization ID when calling BatchGet.

Subject attributes

You can use the List and BatchGet methods to retrieve the values of the following subject attributes:

Note

The subject mask (field-mask) you provide in the List and BatchGet methods should contain field names without the name of the subject main container. e.g., sub, user_account, or service_account.service_agent.microservice_id.

Field	Data type	Attribute
subject: Main container that includes all subject attributes.
`subject.sub`	`string`	ID of the subject
`subject.type`	`enum` ¹	Subject type in the access management system: `1`: User account; matches the `USER_ACCOUNT` value in the response. `2`: Service account; matches the `SERVICE_ACCOUNT` value in the response. `3`: Group; matches the `GROUP` value in the response. `4`: Invited user; matches the `INVITEE` value in the response.
`subject.created_at`	timestamp	Subject creation date and time
`subject.status`	`enum` ¹	Subject status (for federated and local users only): `1`: Active status; matches the `ACTIVE` value in the response. `2`: Inactive status; matches the `SUSPENDED` value in the response.
`subject.name`	`string`	Subject name.
`subject.last_authenticated_at`	timestamp	Last authentication date and time
`subject.external_id`	`string`	Subject ID in the external system
subject.groups: Fields with attributes of groups that include a user or service account. ²
`subject.groups.type`	`enum` ¹	Group type: `1`: Public group; matches the `PUBLIC_ACCESS` value in the response. `2`: User group; matches the `EXPLICIT` value in the response. `3`: System group; matches the `META` value in the response.
`subject.groups.id`	`string`	User group, system group, or public group ID
`subject.groups.name`	`string`	User group, system group, or public group name
subject.user_account: Fields with user-specific attributes.
`subject.user_account.given_name`	`string`	Name
`subject.user_account.family_name`	`string`	Last name
`subject.user_account.preferred_username`	`string`	User's login.
`subject.user_account.email`	`string`	User's email address.
`subject.user_account.phone_number`	`string`	Phone number.
`subject.user_account.expires_at`	timestamp	Scheduled user deactivation date and time, if set. Only for federated and local users.
`subject.user_account.modified_at`	timestamp	Date and time of the most recent update to the user attributes
`subject.user_account.last_id_proof_at`	timestamp	Date and time of the user’s last verification
`subject.user_account.suspend_reason`	`string`	Reason for deactivation (for federated and local users only)
subject.user_account.subject_container: Fields with attributes specific to different user types.
`subject.user_account.subject_container.container_type`	`enum` ¹	Depending on the user type: `1`: User of a SAML-compatible identity federation; matches the `SAML` value in the response. `3`: Yandex account user; matches the `PASSPORT` value in the response. `4`: Local user; matches the `USERPOOL` value in the response.
`subject.user_account.subject_container.id`	`string`	Depending on the user type: For local users: User pool ID. For federated users: Identity federation ID. For Yandex account users: `yandex` value.
`subject.user_account.subject_container.name`	`string`	Depending on the user type: For local users: User pool name. For federated users: Identity federation name. For Yandex account users: `yandex` value.
subject.user_account.job_info: Fields with attributes that describe the user’s company and job title.
`subject.user_account.job_info.company_name`	`string`	Company name
`subject.user_account.job_info.department`	`string`	Department
`subject.user_account.job_info.job_title`	`string`	Job title
`subject.user_account.job_info.employee_id`	`string`	Employee ID
subject.invitee: Fields with attributes specific to Yandex account users who have been invited to the organization but have not yet accepted the invitation.
`subject.invitee.email`	`string`	User's email address.
`subject.invitee.preferred_username`	`string`	User's login.
subject.service_account: Fields with attributes specific to service accounts.
subject.service_account.cloud: Fields with attributes that describe the cloud associated with the service account.
`subject.service_account.cloud.id`	`string`	Cloud ID.
`subject.service_account.cloud.name`	`string`	Name of the cloud.
subject.service_account.folder: Fields with attributes that describe the folder associated with the service account.
`subject.service_account.folder.id`	`string`	Folder ID.
`subject.service_account.folder.name`	`string`	Name of the folder.
subject.service_account.service_agent: Fields with attributes specific to service accounts acting as service agents.
`subject.service_account.service_agent.service_id`	`string`	ID of the service on whose behalf the service agent acts.
`subject.service_account.service_agent.microservice_id`	`string`	ID of the microservice on whose behalf the service agent acts.
subject.group: Fields with attributes specific to user groups, system groups, and public groups.
`subject.group.type`	`enum` ¹	Group type: `1`: Public group; matches the `PUBLIC_ACCESS` value in the response. `2`: User group; matches the `EXPLICIT` value in the response. `3`: System group; matches the `META` value in the response.
`subject.group.id`	`string`	User group, system group, or public group ID
`subject.group.name`	`string`	User group, system group, or public group name

¹ Values of enum-type fields provided in the request filter should use numeric format.
² When using the BatchGet method to get a list of groups that include a Yandex account user, make sure to provide the organization ID in the request.

Subject filter

When getting a list of subjects and their details, you can apply a filter to narrow down the search results and include only the relevant information.

Filters are based on the Common Expression Language (CEL) and set in the filter field.

For more on available CEL features, see this official reference.

In addition to standard CEL features, Identity and Access Management also supports icontains to perform case-insensitive substring matching. Here is an example:

"ABcdEf".icontains("abc") // true

For more info on using filters when getting subject details, see Getting information about subjects in the Yandex Cloud access management system.

Useful links