Help Center/ IAM Identity Center/ API Reference/ API/ Group Management/ Querying Details About Specified User Groups in Batches

Updated on 2025-08-21 GMT+08:00

View PDF

Querying Details About Specified User Groups in Batches

Function

This API is used to query details about specified user groups in batches. It can be called only from the organization's management account or from a delegated administrator account of a cloud service.

URI

POST /v1/identity-stores/{identity_store_id}/groups/batch-query

**Table 1** Path parameters
Parameter	Mandatory	Type	Description
identity_store_id	Yes	String	Globally unique ID of an identity source.

Request Parameters

**Table 2** Parameters in the request header
Parameter	Mandatory	Type	Description
X-Security-Token	No	String	Security token (session token) of your temporary security credentials. If a temporary security credential is used, this header is required.

**Table 3** Parameters in the request body
Parameter	Mandatory	Type	Description
group_ids	Yes	Array of strings	List of unique user group IDs.

Response Parameters

Status code: 200

**Table 4** Parameters in the response body
Parameter	Type	Description
groups	Array of DescribeGroupResp objects	User group list.

**Table 5** DescribeGroupResp
Parameter	Type	Description
description	String	Group description.
display_name	String	Display name of a group.
external_id	String	Identifier assigned by an external identity source to a resource.
external_ids	Array of ExternalIdDto objects	List of resource IDs issued by an external identity provider.
group_id	String	Globally unique ID of an IAM Identity Center group in the identity source.
identity_store_id	String	Globally unique ID of an identity source.
created_at	Long	Creation timestamp.
created_by	String	Creator.
updated_at	Long	Update timestamp.
updated_by	String	Updater.

**Table 6** ExternalIdDto
Parameter	Type	Description
id	String	Resource ID issued by an external identity provider.
issuer	String	Issuer of an external ID.

Status code: 400

**Table 7** Parameters in the response body
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.
request_id	String	Unique ID of a request.

Status code: 403

**Table 8** Parameters in the response body
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.
request_id	String	Unique ID of a request.
encoded_authorization_message	String	Encrypted error message.

Example Request

Querying details about specified user groups in batches

POST https://{hostname}/v1/identity-stores/{identity_store_id}/groups/batch-query

{
  "group_ids" : [ "749aa4a2-6774-4fbb-aefa-94c68cf15a81" ]
}

Example Response

Status code: 200

Successful

[ {
  "description" : "description",
  "display_name" : "group test",
  "group_id" : "749aa4a2-6774-4fbb-aefa-94c68cxxxx1",
  "identity_store_id" : "d-a23adaxxxx",
  "created_at" : 1753794050369,
  "created_by" : "9ec6f4f5dd28485cbcdd9804c5428331",
  "updated_at" : 1753794050369,
  "updated_by" : "9ec6f4f5dd28485cbcdd9804c5428331"
} ]